Development setup
Development setup
Scope
The current workspace includes a source map, strict UTF-8 file-loading primitive, structured diagnostics, and an experimental, narrowly scoped Amiga GFA BASIC 3.5 frontend for the addendum's FACT assignment/PRINT example. The gfabasic build command uses a temporary C/cc bootstrap to produce a native host executable for that subset only. It is not general GFA BASIC support or original-interpreter conformance. General lexical/grammar coverage, semantic analysis, typed IR, LLVM code generation, project configuration, runtime behavior, and platform integration remain unimplemented. These instructions validate the Rust workspace and prototype tests; they do not establish general language compatibility.
The initial CI host is Linux x86-64 using the GitHub-hosted Ubuntu runner. Other development hosts may work with Rust, but are not yet part of the project's validated environment matrix.
Required tools
- Rust 1.99.1, pinned by
rust-toolchain.toml. - The
rustfmtandclippyRust components. - Git.
- A host C compiler exposed as
ccfor the experimentalgfabasic buildcommand and its native executable test. It is not required forcargo build. - Node.js 22 and npm/npx for Markdown linting.
- Python 3.12 with
jsonschema==4.25.1,PyYAML==6.0.2, andmarkdown-it-py==3.0.0for API registry validation, OKF v0.2 validation, and static documentation generation. - lychee v0.24.2 for local Markdown link and anchor checks.
The compiler crate has one third-party Cargo dependency, unicode-width 0.2.2, for terminal display-cell measurement; its MIT OR Apache-2.0 license is within the approved allowlist. The temporary native bootstrap invokes the host cc compiler but requires no additional project runtime library. LLVM and SDL3 are deliberately deferred and are not required to build the Rust workspace. Do not install arbitrary LLVM or SDL3 versions for this stage.
The project source code and original documentation are licensed under MIT. See the root LICENSE and project README. This license does not grant redistribution rights to third-party manuals, ROMs, disk images, or sample programs.
Install the toolchain
Install rustup using the official Rust installation instructions for your operating system. Then run these commands from the repository root:
rustup toolchain install 1.99.1 --profile minimal --component rustfmt --component clippy
rustup default 1.99.1
rustc --version
cargo --version
The toolchain file also selects Rust 1.99.1 when commands run inside this repository.
Build and test
Run the same checks used by the Rust pull-request workflow:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --all-targets
cargo build --workspace --all-targets
The Rust test suite includes focused tests for the narrow FACT/PRINT frontend and a native compile-and-run smoke test; the latter requires cc. There is no general corpus runner and no original-interpreter test suite. Successful Cargo tests validate only the implemented prototype subset and Rust tooling, not full language compatibility.
For documentation changes, run the separate checks:
npx --yes markdownlint-cli2@0.24.0 "**/*.md" "#node_modules"
lychee --offline --include-fragments anchor-only --root-dir "$PWD" "**/*.md"
python -m pip install --disable-pip-version-check jsonschema==4.25.1 PyYAML==6.0.2 markdown-it-py==3.0.0
python scripts/validate_okf.py
python scripts/generate_docs_site.py
python scripts/validate_api_registry.py
python scripts/validate_corpus.py
python -m unittest discover -s scripts/tests -p "test_*.py"
The documentation workflow also validates the OKF bundle, generates build-only HTML pages from the canonical source, validates the API registry and corpus, and runs its validator tests. Run the same checks locally after installing the pinned Python dependency and lychee version:
Troubleshooting
The pinned toolchain cannot be found
Run the rustup toolchain install command above. If the version is unavailable on a host mirror, do not silently substitute a different compiler; report the mirror/toolchain problem and keep CI on the repository pin.
Formatting or Clippy fails
Run the failing command locally with the pinned toolchain. Do not add broad lint suppressions to make the check pass. Fix the source or document a narrowly justified exception.
Cargo reports a lockfile or workspace error
Check that commands run from the repository root and that all workspace members listed in the root Cargo.toml exist. Do not delete Cargo.lock to hide a dependency-resolution difference.
The GFA BASIC build command accepts only the prototype subset
The experimental gfabasic build <source.bas> -o <output> command accepts only the demonstrated Amiga 3.5 FACT assignments to x, y, and z, followed by PRINT x,y,z, with FACT arguments limited to 0, 1, and 2. It requires a working host cc compiler. It does not compile general GFA BASIC or establish original-interpreter compatibility. The check command remains unavailable.
LLVM or SDL3 is missing
These dependencies are not part of the current workspace skeleton. They must be selected and added only in the relevant compiler backend or Linux adapter work, with pinned versions and a reproducible clean-build strategy.
CI parity
- Rust checks run formatting, Clippy, tests, and workspace build on Rust 1.99.1. The supported Ubuntu runner provides
cc, so the native prototype smoke test must execute rather than silently skip. - Documentation checks run Markdown linting, API registry/corpus validation, validator tests, and local-link/anchor validation.
- Fuzzing runs bounded campaigns against the generic source-loader transport boundary only; it does not fuzz a GFA BASIC lexer or parser.
- Security audit checks the root, fuzz, and benchmark Cargo lockfiles against RustSec.
- Benchmarks validate the benchmark harness on pull requests and measure synthetic source loading on main/scheduled/manual runs.
- Release SBOM generates and validates the workspace SPDX 2.3 SBOM on pull requests and is configured to attach it to published GitHub Releases; an actual release upload has not yet been exercised.
These workflows validate repository tooling, source-loading primitives, and the narrow FACT/PRINT prototype path. They do not establish full GFA BASIC language conformance or general compiler/runtime support.
When adding a new check, update this guide and the corresponding workflow in the same change.