How soham-metha/virex works
Project type and purpose
• VIREX is neither a simple web app nor a database-backed service. It’s a toolchain platform comprising:
• A compiler front-end (OCC) for high-level languages (e.g., ORIN) → SASM
• A SASM assembler (reads/writes human-readable assembly)
• A virtual machine (VM) runtime (VIREX) with a text-UI
• Supporting core libraries (univ_*) for file I/O, memory, errors, etc.
• README.md confirms: “any language can compile to SASM” → “runs anywhere VIREX runs.”
File structure
• Top-level directories:
• src/
– OCC/ (parser, lexer, AST, codegen, optimizer for ORIN and other front-ends)
– SASM/ (lexer, parser, AST, binding, expression eval, assembler driver)
– VM/ (core interpreter loop, UI, vmcalls, assembler integration)
– libs/ (univ_defs, univ_fileops, univ_hashmap, etc.)
• include/ (public headers matching each src/*)
• tools/ (editor themes for syntax highlighting in VS Code, Kitty)
• examples/ & tests/ (sample SASM/OCC code, SM binaries)
• build/ releases of SASM and VIREX binaries
• Config/build scripts: Makefile, install.sh, .github/ci.yml, requirements.txt (Graphviz).
README for architectural hints
• README includes three architecture images under docs/assets/Architecture/. These show:
• VIREX overall flow
• SASM assembler internals
• SASM components breakdown
• Tech stack: C, GNU Make, Graphviz for AST viz.
Main components and interactions
a. Compiler Front-End (OCC)
– Sub-components: Lexer → Parser → AST → Inter-code optimizer → Code Generator → SASM output
– Uses “univ_*” core libs for memory, strings, error handling
b. SASM Assembler
– Tokenizer → Parser → AST → Binding/Expression Eval → Instruction Encoder → SM binary output
c. Virtual Machine (VIREX)
– Loader (reads SM binary) → Fetch-Decode-Execute loop → VM Call dispatch → Host runtime (via univ_fileops, univ_errors, etc.)
– UI Layer: Curses-style TUI windows (CreateWindows(), percent-based layout)
d. Core Libraries (shared by OCC, SASM, VM)
e. Developer Tooling
– VS Code syntax highlighter (tools/themes/vs_code…)
– AST Visualizer (Graphviz)
f. External environment
– User’s shell/terminal (fonts, themes)
– OS (file system, console I/O)
1. User/Editor (VS Code, terminal UI)
2. Tooling (syntax highlighter plugin, AST viz)
3. Compilation Pipeline (OCC → SASM assembler)
4. Runtime (VIREX VM)
5. Shared Libraries (univ_*)
6. Host OS
• Source code (ORIN/SASM) → OCC → SASM file → Assembler → SM binary → VM Loader → VM core
• VM core → vmcalls → Core libs → OS
• User keys in menu → VM UI → VM core
• Blue for Compiler
• Green for Assembler
• Orange for VM runtime
• Gray for shared libs
• Yellow for tooling/editor
Architectural patterns & design principles
• Pipeline architecture: sequential phases in compiler & assembler
• Modular layering: clear separation of front-end, back-end, runtime, and tooling
• Reusability: core “univ_” libraries shared by all components
• Extensibility: open SASM instruction set and plugin points for new languages (ORIN)