Skip to content

Readme.md

Latest commit

 

History

History
262 lines (212 loc) · 10.2 KB

Readme.md

File metadata and controls

262 lines (212 loc) · 10.2 KB

FROG logo

FROG Reference Implementation Workspace

Non-normative executable workspace for exercising published FROG corridors from source to runtime and compiler-family proof paths
FROG — Free Open Graphical Language

Overview

This directory contains the non-normative reference implementation workspace for FROG. It exists to make selected repository-visible corridors executable and inspectable without turning implementation convenience into normative language law.

This workspace is public reference material. It exists to exercise the specification and published examples, not to define Graiphic's production runtime, IDE, compiler, or product architecture. Production-grade Graiphic implementations may continue in private repositories while preserving the public contracts required for independent implementations. The public reference runtime material in this repository is bounded to Examples 01 through 15; runtime development for later examples continues in Graiphic's proprietary Graiphic/FROG-Runtime repository unless a later public reference surface is explicitly promoted.

The workspace protects a numbered progression of examples and the published widget / Default realization layer: 

Libraries/Widgets/
Libraries/Realizations/Default/
  -> WidgetValidator

Examples 01-15
  .frog
    -> source-pattern FIR derivation
    -> FIR unit.kind
    -> lowering rule
    -> lowered_unit.kind
    -> backend contract unit.kind
    -> runtime executor kind
    -> runtime acceptance snapshot
    -> LLVM proof

Examples 06-15
  .frog front-panel instances
    -> FIR / lowering / contract artifacts where published
    -> LLVM native kernel artifacts and manifests where published
    -> C++ / Python / Rust runtime-family consumers
    -> .wfrog Default realization packages
    -> SVG public parts and widget-facing browser-host UI

Example 05 remains the primary applicative UI/state/runtime/native corridor. Examples 01-04 provide smaller executable proof slices for pure arithmetic, widget values, UI property writes, and explicit feedback state. Examples 06-15 extend the public reference runtime/widget discipline across the current Boolean, String, Enum, Path, and Button front-panel slices.

Current Reference Corridor Discipline

The current reference workspace is organized around explicit rule handoffs rather than example-name dispatch: 

.frog source pattern
  -> FIR unit.kind
  -> lowered_unit.kind
  -> backend contract unit.kind
  -> runtime executor kind
  -> runtime snapshot

lowered_unit.kind
  -> LLVM proof emitter
  -> module.ll
Stage Dispatch surface Reference documentation
Deriver Recognized source pattern Implementations/Reference/Deriver/rules/Readme.md
Lowerer FIR units[0].kind Implementations/Reference/Lowerer/rules/Readme.md
ContractEmitter lowered_units[0].kind Implementations/Reference/ContractEmitter/
Runtime contract.units[0].kind Implementations/Reference/Runtime/Readme.md
LLVM proof path lowered_units[0].kind Implementations/Reference/LLVM/rules/Readme.md

Published Workspace Shape

Implementations/Reference/
├── ArtifactChecks/
├── CLI/
├── ContractEmitter/
├── Deriver/
├── Loader/
├── Lowerer/
├── Runtime/
├── UIHost/
├── LLVM/
├── Validator/
├── WidgetValidator/
├── check_reference_workspace.py
├── checks.md
├── pipeline.md
└── Readme.md

Stage Responsibilities

  • ArtifactChecks/ verifies that the artifacts announced by the executable corridor exist and have the expected high-level identity.
  • WidgetValidator/ protects the published widget class-law and Default realization layer.
  • Deriver/ derives FIR from supported canonical .frog source patterns. It protects the public .frog -> FIR corridor, but it is not yet a complete derivation engine for every valid future .frog construct or every frog.xxx library function.
  • Lowerer/ lowers supported FIR unit kinds into backend- or compiler-facing lowered unit kinds.
  • ContractEmitter/ emits backend contracts from published lowered unit kinds.
  • Runtime/ checks contract-unit-kind-driven runtime acceptance.
  • LLVM/ checks lowered-unit-kind-to-native proof modules.

The public reference lowerer, contract emitter, and LLVM proof material are bounded conformance corridors. They show how published FIR artifacts can move toward backend-facing proof material without making Graiphic's production lowering bridge, native compiler integration, optimizer, runtime, or deployment packager public implementation requirements.

Primary Checks

python Implementations/Reference/check_reference_workspace.py
python Implementations/Reference/check_reference_workspace.py --widget-layer-only
python Implementations/Reference/check_reference_workspace.py --include-pytest
python Implementations/Reference/check_reference_workspace.py --include-native-kernel-bridge
python Implementations/Reference/check_reference_workspace.py --include-llvm-build

The default workspace command includes the Examples 01-15 public reference pipeline and the current widget-layer validation surface. The --widget-layer-only command exists for fast validation when editing widget class-law documents, Default realization documents, manifests, or SVG resources. The --include-pytest command additionally protects source-pattern derivation, FIR-unit-kind lowering, lowered-unit-kind contract emission, contract-unit-kind runtime execution, lowered-unit-kind LLVM emission, Python runtime UI coverage for the current widget examples, and unsupported-pattern / unsupported-kind failure behavior. The --include-native-kernel-bridge command validates the published native-kernel bridge surface where the local native toolchain is available.

Fresh Clone Environment

The repository contains the FROG source examples, published artifacts, reference runtimes, widget realization packages, SVG assets, LLVM-oriented proof material, and validation scripts. A clean clone can therefore reproduce the current reference workspace, provided the local machine supplies the required development tools.

Minimum practical environment for the reference workspace:

  • python with pip, used by the reference checks and Python runtime tests,
  • pytest, installed with python -m pip install pytest,
  • cmake and a C++ toolchain, used by the C++ runtime checks,
  • cargo / Rust toolchain, used by the Rust runtime checks,
  • clang, required only for LLVM native build and native-kernel bridge checks.

Recommended validation sequence after a clean clone: 

python -m pip install pytest
python Implementations/Reference/check_reference_workspace.py --include-pytest

cmake -S Implementations/Reference/Runtime/cpp -B build/frog_runtime_cpp
cmake --build build/frog_runtime_cpp
ctest --test-dir build/frog_runtime_cpp --output-on-failure

cargo test --manifest-path Implementations/Reference/Runtime/rust/Cargo.toml

When clang is available, the native proof and native-kernel bridge checks can also be run: 

python Implementations/Reference/check_reference_workspace.py --include-llvm-build
python Implementations/Reference/check_reference_workspace.py --include-native-kernel-bridge

The standard runtime checks must remain usable without making LLVM a mandatory runtime dependency. LLVM is a backend/native-kernel artifact producer; the runtimes consume manifest-declared ABI surfaces and the corresponding .wfrog front-panel realization packages.

The reference workspace also does not require FROG deployment to mean "ship the entire reference runtime." The public reference path keeps the current bounded examples inspectable. Future production or independent implementations may compile accepted scopes into generated launchers, self-contained executables, or other selected dependency closures when the backend contract and applicable profiles make the required services and dependencies explicit.

Continuous Integration

The repository publishes a GitHub Actions workflow for the reference workspace: 

.github/workflows/reference-workspace.yml

The workflow runs the full reference workspace check, the reference pytest suite, and the widget-layer-only check on relevant repository changes.

Ownership Boundary

This workspace consumes the published specification layers. It does not define FROG source law, semantic law, FIR law, widget law, realization law, runtime law, backend contract law, or LLVM backend law. It also does not define Graiphic's production implementation space. 

reference implementation
  !=
language definition