GFA BASIC Rust Documentation

ADR 0005: CLI and project configuration

Architecture Decision Record

ADR 0005: CLI and project configuration

  • Status: Accepted
  • Date: 2026-11-04

Context

The project needs an explicit and reproducible way to select source dialect/version, API profiles, and output target. Configuration discovery and precedence must not silently change language semantics. The CLI must also distinguish source diagnostics from configuration and toolchain failures.

Decision

  1. Name the executable `gfabasic` and use the initial commands `build`, `check`, and `version`.
  2. Use a TOML project file named `gfabasic.toml`, with an independent integer schema version.
  3. Discover the nearest project file upward from the source parent directory, or from the current directory when no source is supplied. An explicit `--project PATH` disables discovery.
  4. In single-file mode without a project file, require explicit dialect identifier and version on the command line.
  5. Resolve settings by command line > project file > safe documented default. Dialect and version have no implicit default; API profiles default to none; target defaults to the accepted initial Linux target.
  6. Keep dialect/version, API profile set, and output target independent. Never infer dialect or profile from file extension, source text, or target.
  7. Use project-relative paths resolved from the project file directory.
  8. Use `build/<target-triple>/` as the default target-specific output directory. The initial output is a native executable; optional artifacts are exposed only after implementation.
  9. Define stable exit-status categories for success, source diagnostics, configuration/usage errors, backend/toolchain failures, and filesystem/environment failures.
  10. Write diagnostics to stderr. Write machine-readable reports only when explicitly requested. Do not execute arbitrary commands from project configuration or require network/LLM services.

The detailed policy is maintained in CLI-AND-CONFIG.md. Exact schema validation and implementation are separate work.

Alternatives considered

  • JSON or YAML project files: rejected for the initial project configuration in favor of TOML, which is already familiar in Rust tooling and supports comments.
  • Implicit dialect inference from extension/content: rejected because it can silently select incorrect historical semantics.
  • Implicit API profile from output target: rejected because source API semantics and output target are independent.
  • Configuration precedence in which project files override CLI options: rejected because explicit command-line options must remain the highest-precedence override.
  • One output directory shared by all targets: rejected because it risks cross-target artifact collisions.
  • Running project-defined shell commands during compilation: rejected because configuration must not become an arbitrary code-execution mechanism.

Consequences

  • CLI and configuration must preserve the accepted dialect/profile/target separation from ADR 0004 and the target identity from ADR 0003.
  • The project-file schema must be independently versioned and validated.
  • Source dialect/version selection is mandatory and explicit.
  • The initial target has a documented default, but cross-compilation is not implied.
  • The interface remains partially implemented. The executable provides help/version, a bounded formatter for the verified source subset, and an experimental build path for literal FACT/VARIAT/COMBIN assignments followed by PRINT using a temporary C/cc bootstrap. The check command explicitly remains unavailable. Project loading, TOML configuration validation, project discovery, general parser/semantic integration, LLVM code generation, compatibility reports, and artifact manifests remain future work. The prototype does not imply general GFA BASIC support or interpreter conformance.

References