README.md

 ██████╗ █████╗ ███████╗██████╗ ██████╗ ██╗██╗  ██╗
██╔════╝██╔══██╗██╔════╝██╔══██╗██╔══██╗██║╚██╗██╔╝
██║     ███████║███████╗██████╔╝██████╔╝██║ ╚███╔╝ 
██║     ██╔══██║╚════██║██╔═══╝ ██╔══██╗██║ ██╔██╗ 
╚██████╗██║  ██║███████║██║     ██║  ██║██║██╔╝ ██╗
 ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝

👻 What is Casprix?

Casprix is a compiled, statically-typed systems programming language designed for developers who need both expressiveness and raw performance. It compiles directly to x86-64 native code via a multi-stage optimizing compiler pipeline, achieving runtime speeds 5–10x faster than unoptimized equivalents — with a compilation pipeline 7.5x faster thanks to its arena allocator.

Casprix combines:

• The safety model of modern systems languages (ownership, borrow annotations, lifetime regions)
• The expressiveness of high-level languages (closures, generics, async/await, traits)
• The performance of hand-optimized C (SIMD vectorization, register allocation, loop unrolling)

✨ Language Features

🏗️ Compiler Architecture

Casprix uses a multi-stage optimizing compiler centered around a typed IR. The pipeline is designed for correctness first, then aggressive optimization.

The pipeline flows through five distinct stages:

Frontend — lexing, parsing, name resolution, type inference, monomorphization, and closure lowering. Produces a clean, typed AST ready for IR conversion.

IR (typed SSA) — the heart of the compiler. An explicit control flow graph with basic blocks, phi nodes, ownership annotations, lifetime regions, and stack/heap abstraction. Two analysis passes run here: the Borrow Checker (static aliasing and race prevention) and the Const-Eval Engine (compile-time execution with termination guarantees).

Optimization Pipeline — 8 ordered passes over the IR. Each pass unlocks the next: constant propagation enables copy propagation, which enables dead code elimination, and so on through inlining, escape analysis, strength reduction, control flow simplification, and loop optimization.

Backend Abstraction Layer — target-independent interface handling ABI, calling conventions, and register abstraction. Decouples the optimizer from the code generator and enables multiple backends.

Backends — AOT native (x86-64 NASM today, ARM64 planned), register-based MIR VM with a CVM interpreter and experimental JIT bridge under runtime/vm/, and a fuller tiered JIT (roadmap).

🧠 Memory Model

Casprix uses a hybrid memory model — the compiler's escape analysis pass decides at IR time where each allocation lives:

• Stack — locals that don't escape their scope. Zero overhead, freed automatically.
• Ownership heap — values with a single owner that outlive their scope. Freed deterministically on drop.
• Memory regions (arena) — bulk lifetime allocations freed all at once. Responsible for the 7.5x compile speedup.
• GC — available for managed objects and cyclic graphs. Opt-in, not default.

All allocation decisions are static — no runtime type checks, no boxing overhead.

⚙️ VM & JIT Architecture

VM Bytecode uses a register-based instruction format (not stack-based), reducing instruction count and dispatch overhead. The tree ships a CVM interpreter and JIT bridge in runtime/vm/ (used by tests such as test_vm_jit); the full productized VM + security story is still evolving.

Tiered JIT (target design) operates in four levels:

1. Tier 0 (Baseline) — fast emission, minimal optimization, gets code running immediately
2. Profiling — call counters and branch frequency tracking identify hot paths
3. Tier 2 (Optimizing) — speculative optimization with inline caches and type feedback
4. Deopt / OSR — guard failures trigger deoptimization; on-stack replacement allows mid-execution tier transitions

📊 Performance Benchmarks

Compilation Speed

Runtime Performance

Optimizations: register allocation + SIMD vectorization + loop unrolling + constant folding + inlining.

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/wmndilshan/casprix.git
cd casprix

# Build (Linux / macOS)
scripts/build.sh

# Build (Windows — cmd from repo root)
scripts\build.bat

On Windows with a multi-config generator (Visual Studio), the compiler is often build\Release\casprix.exe. With Ninja or single-config CMake, it is usually build\casprix.exe.

Hello, World!

# hello.cpx
print("Hello, Casprix! 👻")

build/casprix hello.cpx -o build/hello
./build/hello
# → Hello, Casprix! 👻

On Windows, run build\hello.exe or build\Release\hello.exe depending on your CMake generator.

Compile with Optimizations

casprix program.cpx -o output --opt-level=2
casprix --help            # -O0, --mir, --native, --vm, --jit, …

📖 Language Guide

Variables & Types

let x: int    = 42
let name: string = "Casprix"
let pi: float = 3.14159
let flag: bool = true

Functions

func add(a: int, b: int) -> int {
    return a + b
}

let result = add(5, 3)  // result = 8

Closures

let increment = |x: int| => x + 1

Pipe-lambda syntax is available, but captured closures and first-class closure calls are still being finished in the current front end. See examples/basic/closures.cpx as a planned-surface reference rather than a guaranteed compiling sample.

Generic Types

class List<T> {
    mut items: array<T>;
    mut count: int;

    func add(item: T) {
        this.items[this.count] = item
        this.count = this.count + 1
    }
}

let numbers = new List<int>()
numbers.add(42)

Async / Await

Async / await is planned for CASPRIX, but the current parser does not accept it yet. Keep async examples out of the main language guide until the surface syntax is wired end to end.

Traits

trait Printable {
    func toString() -> string
}

class Point {
    let x: int;
    let y: int;
}

impl Printable for Point {
    func toString() -> string {
        return "(" + this.x + ", " + this.y + ")"
    }
}

Pattern Matching

func describe(x: int) -> string {
    match x {
        0     => "zero",
        1..9  => "single digit",
        10..99 => "two digits",
        _     => "large number"
    }
}

Classes & Inheritance

class Animal {
    let name: string;
    func speak() -> string { return "..." }
}

class Dog extends Animal {
    func speak() -> string {
        return "Woof! I'm " + this.name
    }
}

🔧 Optimization Pipeline

Pass 1 — Const Propagation      Folds compile-time-known values inline
Pass 2 — Copy Propagation       Eliminates redundant variable copies
Pass 3 — Dead Code Elimination  Removes unreachable branches and unused defs
Pass 4 — Function Inlining      Expands small hot functions at call sites
Pass 5 — Escape Analysis        Stack-promotes heap allocations where safe
Pass 6 — Strength Reduction     Replaces expensive ops with cheaper equivalents
Pass 7 — CF Simplification      Merges/eliminates redundant basic blocks
Pass 8 — Loop Optimization      Invariant hoisting, 4x unrolling, AVX2 vectorization

Backend applies linear scan register allocation (85–90% utilization) and AVX2 auto-vectorization on eligible loops.

📦 Package Manager

The CMake target installs as casprix-pkg (CLI help text uses the cpkg command name). Example:

casprix-pkg init              # initialize project
casprix-pkg install http      # install package
casprix-pkg install json@^1.5 # with version constraint

Version Constraints

casper.json (package manifest)

{
    "name": "myapp",
    "version": "1.0.0",
    "dependencies": {
        "http":   "^2.0.0",
        "json":   "^1.5.0",
        "crypto": "~3.1.0"
    }
}

Quick Start · Language Guide · Architecture · Contributing · Benchmarks · Package Manager · Docs

🗂️ Project Structure

casprix/
├── src/compiler/
│   ├── frontend/        # Lexer, parser, AST
│   ├── sema/            # Type checking, escape analysis, ownership
│   ├── middle/          # Closures, generics, traits, async lowering
│   ├── ir/              # MIR (SSA), borrow checker, optimizations
│   ├── codegen/         # x86-64 NASM generation, regalloc
│   └── opt/             # Loop opt, SIMD, inlining, peephole
├── runtime/             # Runtime library (C)
│   ├── memory/          # GC, regions, refcount, ownership
│   ├── vm/              # CVM interpreter + JIT bridge (MIR VM)
│   ├── async/           # Async/await coroutine scheduler
│   ├── net/             # Networking stack
│   ├── ai/llm/          # Transformer / training runtime (AVX2)
│   ├── ai/nn/           # Neural-network layers (C API)
│   └── skia/            # Optional Skia/GDI GUI (ENABLE_SKIA_GUI)
├── include/             # Public C headers
├── lib/                 # Casprix standard modules (.cpx)
├── stdlib/              # Bootstrap stdlib package index
├── pkg/                 # Package manager (builds as casprix-pkg)
├── tools/               # apk-builder, training helpers, …
├── scripts/             # build.sh / build.bat, test runners
├── tests/               # CTest: runtime, compiler, MIR, Android helpers
└── examples/
    ├── basic/           # Hello world, variables, functions
    ├── advanced/        # Closures, generics, pattern matching
    ├── gui/             # Skia UI samples (.cpx)
    ├── llm_training/    # TinyStories-style training sketch
    ├── network/         # Networking
    └── tinystories/     # End-to-end TinyStories pipeline (.cpx)

📈 Project Statistics

🗺️ Roadmap

• x86-64 AOT native code generation
• Arena allocator + MIR optimization pipeline
• Generics with monomorphization
• Closures with variable capture (surface still evolving)
• Async/await runtime
• Built-in package manager (casprix-pkg / cpkg CLI)
• MIR VM + CVM interpreter + experimental JIT bridge (runtime/vm/)
• Tiered JIT compiler (full pipeline)
• ARM64 native target
• Full borrow checker (end-to-end)
• LSP language server
• Self-hosted compiler

Documentation

• Feature Summary
• Project Structure
• Stdlib, strings, StringView, and regex
• Package Manager Guide
• Standard library sources live under lib/ (Casprix modules) and stdlib/ (bootstrap index)

License

MIT License — see LICENSE for details.