Skip to content

Readme.md

Latest commit

 

History

History
256 lines (203 loc) · 10.4 KB

Readme.md

File metadata and controls

256 lines (203 loc) · 10.4 KB

FROG logo

Reference Runtime (C/C++)

C/C++ realization of the published reference_host_runtime_ui_binding family
FROG — Free Open Graphical Language

Repository governance and publication state are centralized in Versioning/Readme.md.

Directory Navigation

Implementations/Reference/Runtime/cpp/
├── Readme.md
├── CMakeLists.txt
├── include/
│   ├── contract.hpp
│   ├── execute.hpp
│   ├── json.hpp
│   ├── kernel_bridge.hpp
│   ├── runtime.hpp
│   └── ui.hpp
├── src/
│   ├── contract.cpp
│   ├── execute.cpp
│   ├── json.cpp
│   ├── kernel_bridge.cpp
│   ├── main.cpp
│   ├── main_llvm_kernel.cpp
│   ├── runtime.cpp
│   └── ui.cpp
└── tests/
    ├── test_slice05.cpp
    ├── test_slice05_llvm_kernel.cpp
    ├── test_slice06_boolean.cpp
    ├── test_slice06_llvm_kernel.cpp
    ├── test_slice07_string.cpp
    ├── test_slice07_llvm_kernel.cpp
    ├── test_slice08_enum.cpp
    ├── test_slice08_llvm_kernel.cpp
    ├── test_slice09_path.cpp
    ├── test_slice09_llvm_kernel.cpp
    ├── test_slice10_button.cpp
    ├── test_slice10_llvm_kernel.cpp
    └── test_slice11_button_switch.cpp

Role

This directory contains the C/C++ consumer for the published Examples 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, and 15 runtime slices. It accepts emitted backend contracts, loads the published .wfrog packages, resolves the referenced SVG assets, exposes browser-host UIs, and can run either the default contract-executor path or the optional manifest-declared native-kernel bridge path.

This directory is a runtime-family consumer. It is not a language-definition layer, not a compiler-family layer, and not a substitute for canonical source, FIR, lowering, or backend compilation.

Standard Runtime Executable

frog_reference_runtime_cpp

The standard executable supports:

  • headless execution by default or through run,
  • browser-host UI through ui.

It remains available without LLVM or clang. It executes the bounded Example 05, Example 06, Example 07, Example 08, Example 09, Example 10, Example 11, Example 12, Example 13, Example 14, and Example 15 backend contracts and produces the published runtime artifacts. 

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

build/frog_runtime_cpp/frog_reference_runtime_cpp 3
build/frog_runtime_cpp/frog_reference_runtime_cpp run true --example 06
build/frog_runtime_cpp/frog_reference_runtime_cpp run "hello world" --example 07
build/frog_runtime_cpp/frog_reference_runtime_cpp run fault --example 08
build/frog_runtime_cpp/frog_reference_runtime_cpp run "C:/FROG/hello_world.txt" --example 09
build/frog_runtime_cpp/frog_reference_runtime_cpp run true --example 10
build/frog_runtime_cpp/frog_reference_runtime_cpp run true --example 11
build/frog_runtime_cpp/frog_reference_runtime_cpp ui --host 127.0.0.1 --port 8080 --no-open-browser

Native-Kernel Runtime Executable

frog_reference_runtime_cpp_llvm_kernel

The optional native-kernel executable is built when FROG_RUNTIME_CPP_ENABLE_LLVM_KERNEL_BRIDGE=ON. CMake compiles the published Example 05, Example 06, Example 07, Example 08, Example 09, Example 10, Example 11, Example 12, Example 13, Example 14, and Example 15 kernel.ll artifacts with clang, links the resulting objects into the executable, and uses native_kernel_manifest.json to validate and call the selected ABI surface.

This executable is the bounded Example 05, Example 06, Example 07, Example 08, Example 09, Example 10, Example 11, Example 12, Example 13, Example 14, and Example 15 LabVIEW-like proof path: 

.frog source
  -> FIR
  -> lowering
  -> LLVM-produced kernel.ll
  -> native kernel manifest

.frog front panel
  -> C++ browser-host renderer
  -> widget instance layout, style, and binding

.wfrog realization package
  -> SVG skins and anchor/value overlays

runtime C++
  -> NativeKernelBridge
  -> frog_example05_run(input_value, out_result)
  -> or frog_example06_run(input_value, out_result)
  -> or frog_example07_run(input_text, out_result)
  -> or frog_example08_run(mode_value, out_result)
  -> or frog_example09_run(input_path, out_result)
  -> or frog_example10_run(trigger_pressed, out_result)
  -> or frog_example11_run(trigger_value, out_result)
  -> or frog_example12_run(trigger_value, out_result)
  -> or frog_example13_run(trigger_value, out_result)
  -> or frog_example14_run(trigger_value, out_result)
  -> or frog_example15_run(trigger_value, out_result)
  -> public result
  -> matching indicator value
  -> runtime snapshot / state.json

python Implementations/Reference/Runtime/check_example05_cpp_native_kernel_bridge.py
python Implementations/Reference/Runtime/check_example06_cpp_native_kernel_bridge.py

build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel 3
build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel run true --example 06
build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel run "hello world" --example 07
build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel run fault --example 08
build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel run "C:/FROG/hello_world.txt" --example 09
build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel run true --example 10
build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel run true --example 11
build/frog_runtime_cpp_native_kernel_bridge/frog_reference_runtime_cpp_llvm_kernel ui --host 127.0.0.1 --port 8080 --no-open-browser

Browser-Host UI Fidelity

The current C++ browser-host renderer consumes each published example .wfrog package as the panel layout authority. It renders:

  • the front panel in panel_pixels,
  • the widget x, y, width, and height declarations,
  • the Default Numeric, Boolean, String, Enum, Path, and Button SVG skins as the widget bodies for Examples 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, and 15,
  • published realization anchors including caption.anchor, value/text surfaces, and the Numeric increment_up / increment_down parts,
  • dynamic widget values and labels,
  • contract-driven foreground_color property writes.

The Example 05 panel uses the shared Default Numeric realization. Example 06 uses the shared Default Boolean realization. Example 07 uses the shared Default String realization without a published String focus-ring part. Example 08 uses the shared Default Enum realization. Example 09 uses the shared Default Path realization without an invisible outer frame or focus-ring hover target. Examples 10 through 15 use the shared Default Button realization for the command and the shared Default Boolean realization for the read-only indicator while covering the six published Button mechanical actions. This is a bounded fidelity pass for the current published examples, not a complete generalized .wfrog renderer.

Native Kernel Bridge Surface

native_kernel_manifest.json
  -> NativeKernelManifest
  -> NativeKernelBridge
  -> frog_example05_run(input_value)
  -> FrogRunResult { ok, result, error_code }
  -> runtime result / diagnostic / snapshot

The runtime consumes a manifest-declared function pointer. The fact that the first published backend artifact is LLVM-oriented remains manifest metadata, not a runtime-core dependency.

Tests

The standard C/C++ test target checks:

  • headless execution with input 3 and final result 15,
  • overflow rejection behavior,
  • native-kernel bridge behavior with an ABI-compatible stub,
  • browser-host HTML rendering with both SVG asset routes,
  • .wfrog / SVG geometry coherence for Example 05 Numeric widgets, Example 06 Boolean widgets, Example 07 String widgets, Example 08 Enum widgets, Example 09 Path widgets, and Example 10/11/12/13/14/15 Button plus Boolean widgets.

The optional LLVM-produced native-kernel bridge target checks:

  • manifest loading, entry-symbol validation, ABI validation, and error mapping,
  • direct calls through an object compiled from kernel.ll,
  • runtime snapshot publication through execute_with_native_kernel_bridge(...),
  • browser UI runtime execution through the current Numeric, Boolean, String, Enum, Path, and Button browser-host runtimes with a native kernel bridge.

Non-Goals

  • General runtime support for arbitrary contracts.
  • Language or widget-law ownership.
  • Compiler-family responsibilities.
  • Native compiled UI closure.
  • A complete generalized .wfrog renderer.
  • A complete LabVIEW-like runtime surface.
  • A mandatory runtime dependency on LLVM or clang.

Summary

Read this directory as the C/C++ proof path for the current runtime family: 

contract + .wfrog + SVG assets
=> C/C++ runtime core
=> headless result or browser-host UI

native kernel manifest + linked ABI-compatible kernel
=> C++ NativeKernelBridge
=> same runtime result / diagnostic / snapshot surface

kernel.ll + clang + optional CMake target
=> native-kernel runtime executable
=> hosted .wfrog UI calling a compiled diagram kernel