How vtereshkov/umka-lang works
Project Type and Purpose
• Type: A language toolchain (compiler + virtual machine) with embed API and multi-platform builds.
• Purpose:
– Compile Umka source files (.um) to bytecode
– Execute bytecode in a lightweight VM with reference-counting GC
– Offer a C API for embedding
– Provide a browser playground via Emscripten
– Ship standard library (runtime/*.um)
– Support cross‐platform builds and packaging (Homebrew, UmBox)
File Structure
• src/ → Compiler & VM modules (lexer, parser, semantic, codegen, VM, runtime, API).
• runtime/ → Umka standard library in Umka itself (.um), GC helpers, UTF-8 support.
• playground/umka.js, run_emscripten* → Emscripten-compiled VM for browser.
• examples/ → Embedding examples (3dcam, raytracer, Lisp).
• tests/ → Umka test suite, harness scripts.
• build_*.sh/.bat, Makefile → Cross-platform build scripts.
• .github/workflows → CI pipelines for building/testing (including UmBox packaging).
• doc/ → Language, API, library documentation.
README for Technical Insights
• Language features (static typing, fibers, GC).
• Embedding API (C99 static/dynamic library).
• Playground (web UI).
• Packaging (UmBox, Homebrew).
• Example integration (raylib, game frameworks).
Main Components & Relationships
a. Source Inputs
– Umka source files (.um) & examples
– Standard library scripts (runtime/*.um)
b. Compiler Pipeline (src/)
– Lexer → Parser → Semantic Analyzer → Intermediate Representation → Code Generator
– Produces bytecode (in‐memory or on‐disk module)
c. Virtual Machine & Runtime
– Bytecode loader/executor (src/umka_vm.c)
– Garbage collector (reference counting)
– Runtime support (memory, UTF8, math, fibers)
d. Embedding API
– C functions (src/umka_api.{h,c})
– Header/API layer exposed to hosts
e. Tooling & Packaging
– CLI tool (umka.exe/umka)
– Playground (Emscripten build: umka.js + HTML)
– Build scripts for Windows, Linux, macOS, WASM
– CI (GitHub Actions) & UmBox packaging
Architectural Patterns & Design Principles
• Pipeline pattern for compiler stages
• Layered architecture:
– Presentation (CLI, Playground UI)
– Processing (compiler modules)
– Execution (VM + runtime)
– Integration (C API)
• Modular C code organized by responsibility (lexer, parser, stmt, expr, gen, vm, runtime, API)
• Cross-compilation targets via build scripts and Emscripten wrapper
• Test harness drives compiler + VM on sample scripts
Final Checklist
[ ] All major components labeled
[ ] Notes on key technologies (C99, Emscripten, reference-count GC)
[ ] Representation of tests and CI as validation lanes (optional)
[ ] Clear separation of layers: Input → Compile → Execute → Embed → Deploy