How kuroko-lang/kuroko works
Project Type and Purpose
• Kuroko is a programming‐language implementation: a dynamic, bytecode-compiled Python dialect.
• It provides a compiler (turns KrK source into bytecode), a VM/interpreter (executes bytecode), a REPL/CLI, a C API for embedding, plus standard library modules and tooling.
High-Level Architecture Components
a. Build System
• Makefile + GitHub workflows → compiles C sources into:
– kuroko CLI executable (integrates compiler + VM)
– libkuroko.{a,so} shared/static library for embedding
b. Compiler Frontend
• src/compiler.c, src/scanner.c, src/kuroko/*.h → parse KrK source, generate bytecode chunks
c. Virtual Machine & Runtime
• src/vm.c, src/memory.c, GC (tracing collector), threading support (src/threads.c)
• Core interpreter loop, opcode definitions (src/opcodes.h), object model (src/object.c, src/obj_*.c)
d. Builtin and Extension Modules
• src/modules/*.{c,krk} → C‐based modules (math, os, socket, etc.)
• modules/*.krk → standard library in KrK scripts
e. REPL/CLI Layer
• kuroko binary: wires together the frontend, VM, line editor, disassembler (if enabled)
f. Embedding API
• public headers (src/kuroko/*.h) → host applications link against libkuroko to embed interpreter
g. Tools, Benchmarks, Testing & Documentation
• tools/ → utility programs (e.g., code generators, sandbox)
• bench/ → performance tests comparing bytecode vs. Python
• test/ → comprehensive KrK test suite
• docs/ → Doxygen config+ markdown user/embedding/compiler docs
Interactions and Data Flow
• KrK source file → (CLI or embedding host) → Compiler Frontend → Bytecode
• Bytecode → Virtual Machine → Executes instructions, allocates/traces objects, schedules threads
• VM loads modules on import: either C‐based (dynamically linked) or KrK scripts
• REPL feeds source lines into the compiler, then executes via VM
• Host application → C API calls to initialize VM, load scripts/modules, run bytecode
Architectural Patterns & Principles
• Layered design: clear separation between parsing/compilation, runtime engine, and embedding interface
• Modular extensibility: additional modules in C or KrK; third‐party embedding via stable C ABI
• Configurable build flags control features (debugging, docs, line editor)
5. Off of VM, show “Standard Library” layer split into:
– C Extension Modules (src/modules)
– KrK Module Scripts (modules/)
Final Touches
• Build‐time flags and supported platforms