bux-lang/README.md

Bux Programming Language

Status: v0.5.0 — Bootstrap compiler (buxc, Nim) and self-hosted compiler (buxc2, Bux) both compile .bux → C → native binary. Selfhost loop: buxc2 compiles itself → binary-identical buxc3 ✅ Deterministic C codegen + ELF verified. Gradual Ownership: @[Checked] borrow checker, @[Release] zero-cost mode, borrow &mut expressions. Green Threads: M:N scheduler with channels (Go-style goroutines without GC). All 26 examples pass. Compiler successfully parses all 3 real-world apps (apps/boko-framework, apps/jwt-pitbul, apps/nexus).

Bux is a fast, compiled, strongly-typed systems programming language. Features a C backend for native code generation, raw multi-line strings, gradual ownership (opt-in borrow checking), async/await, generics, algebraic enums, and a package manager.

---

Quick Start

# Build the bootstrap compiler (Nim)
make build

# Create a new project
bux new hello
cd hello

# Build and run
bux run

# Build optimized release binary
bux build --release

# Cross-compile for ARM Linux (requires clang)
bux build --target aarch64-linux-gnu

---

Syntax Preview

Hello World

import Std::Io::PrintLine;

func Main() -> int {
    PrintLine("Hello, Bux!");
    return 0;
}

Raw Multi-line Strings

// Backtick strings: no escape processing, multi-line
func Main() -> int {
    PrintLine(`Hello \n World`);     // prints: Hello \n World (literal)
    PrintLine(`Line 1
Line 2
Line 3`);                            // multi-line, newlines preserved
    return 0;
}

Error Handling with ?

enum Result {
    Ok(int),
    Err(String)
}

func Divide(a: int, b: int) -> Result {
    if b == 0 {
        return Result_NewErr("division by zero");
    }
    return Result_NewOk(a / b);
}

func Compute() -> Result {
    let x: int = Divide(10, 2)?;  // auto-propagates Err
    let y: int = Divide(x, 5)?;
    return Result_NewOk(y);
}

Structs and Methods

struct Rectangle {
    width: int;
    height: int;
}

extend Rectangle {
    func Area(self: Rectangle) -> int {
        return self.width * self.height;
    }
}

func Main() -> int {
    let rect: Rectangle = Rectangle { width: 10, height: 5 };
    PrintInt(rect.Area());
    return 0;
}

Generics

func Max<T>(a: T, b: T) -> T {
    if a > b {
        return a;
    }
    return b;
}

func Main() -> int {
    let m: int = Max<int>(10, 20);
    PrintInt(m);
    return 0;
}

Async/Await

import Std::Io::{PrintLine, PrintInt};

async func Compute() -> int {
    PrintLine("Compute: step 1");
    bux_async_yield();
    PrintLine("Compute: step 2");
    return 42;
}

func Main() -> int {
    let h1 = spawn Compute();
    let r1: int = h1.await as int;
    PrintInt(r1);
    return 0;
}

Channels (Producer/Consumer)

import Std::Io::{PrintLine, PrintInt};
import Std::Task::{Task_Wait, TaskHandle};
import Std::Channel::{Channel, Channel_New, Channel_SendInt, Channel_RecvInt, Channel_Close};

func Producer(chPtr: *Channel<int>) {
    var i: int = 1;
    while i <= 5 {
        Channel_SendInt(chPtr, i * 10);
        i = i + 1;
    }
    Channel_Close<int>(chPtr);
}

func Consumer(chPtr: *Channel<int>) {
    var total: int = 0;
    while true {
        let val: int = Channel_RecvInt(chPtr);
        if val == 0 { break; }
        total = total + val;
        PrintInt(val);
        PrintLine("");
    }
    PrintLine("Total:");
    PrintInt(total);
    PrintLine("");
}

func Main() -> int {
    let ch: Channel<int> = Channel_New<int>(3);
    let p: *void = spawn Producer(&ch);
    let c: *void = spawn Consumer(&ch);
    Task_Wait(TaskHandle { handle: p });
    Task_Wait(TaskHandle { handle: c });
    return 0;
}

Hash Map

import Std::Map::{Map, Map_New, Map_Set, Map_Get};

func Main() -> int {
    let m: Map = Map_New(16);
    Map_Set(&m, "answer", 42);
    PrintInt(Map_Get(&m, "answer"));
    return 0;
}

---

Features

Feature	Status
Types	Primitives, pointers, slices, tuples, structs, enums, unions
Generics	Generic functions (monomorphization)
Algebraic Enums	Enums with data (Result, Option)
Pattern Matching	match with guards
Methods	extend blocks for struct methods
Interfaces	interface + extend for trait-like behavior
Error Handling	Result<T,E>, Option<T>, and the ? operator
Standard Library	Io, Array, String, Map, Fs, Mem, Set, Path, Math, Task, Channel, Sync, Os, Time, Process
Backend	LIR → C transpiler (clean 3-address code, then gcc/clang)
Strings	Raw multi-line backtick strings (...), C-string interop
Gradual Ownership	@[Checked] + @[Release] + @[Shared] + borrow &mut / borrow &
Drop Trait	Auto-drop for @[Drop] types (Array, Map, user-defined structs)
Green Threads	M:N scheduler (ucontext + SIGVTALRM), work-stealing queues
Async/Await	async func, spawn, .await with stackful coroutines
Concurrency	Task/Channel/Sync (pthread-based), bux_async_yield/spawn
CTFE	const func — compile-time function execution
Trait Bounds	func Max<T: Comparable>(a: T, b: T) -> T
Package Manager	bux add, bux install, bux.lock, path + git deps
Cross-Compilation	--target <triple> via clang (e.g. aarch64-linux-gnu)
Tooling	bux new, bux build, bux run, bux test, bux check

---

Project Structure

bux/
├── src/              # 🎯 Self-hosting compiler source (Bux)
│   ├── main.bux      # Entry point
│   ├── lexer.bux     # Tokenizer
│   ├── parser.bux    # Pratt parser
│   ├── ast.bux       # AST node types
│   ├── sema.bux      # Type checker
│   ├── hir_lower.bux # AST → HIR lowering
│   ├── c_backend.bux # HIR → C code generator
│   └── cli.bux       # CLI driver
├── bootstrap/        # 🔧 Bootstrap compiler (Nim)
│   ├── main.nim      # Entry point
│   ├── cli.nim       # CLI commands + build driver
│   └── ...           # (mirrors src/ structure)
├── lib/              # 📦 Standard library (23 modules)
│   ├── Io.bux        # Print, ReadFile, WriteFile
│   ├── String.bux    # Full string API
│   ├── Array.bux     # Generic Array<T>
│   ├── Map.bux       # Generic Map<K,V> + StringMap
│   ├── Set.bux       # Generic Set<T>
│   ├── Task.bux      # Green threads (spawn/await)
│   ├── Channel.bux   # Producer/consumer channels
│   ├── Drop.bux      # Drop trait interface
│   └── ...           # Math, Fs, Path, Sync, Result, ...
├── rt/               # ⚙️ C runtime
│   ├── runtime.c     # Memory, scheduler, channels
│   └── io.c          # File I/O wrappers
├── tests/            # 🧪 Unit tests (Nim)
├── examples/         # Example programs
├── apps/             # Real-world applications
├── docs/             # Documentation
├── README.md
├── PLAN.md           # Roadmap to v1.0.0
└── Makefile

---

Build & Test

# Build bootstrap compiler (Nim → C)
make build

# Build self-hosted compiler (Bux → C → native)
make selfhost

# Run all tests
make test

# Run example programs
make test-examples

# Verify selfhost binary parity (buxc2 → buxc3, identical)
make selfhost-loop

# Clean build artifacts
make clean

Windows users: Use the buxs/ directory as your project root to avoid path conflicts.

---

Applications

The apps/ directory contains real-world Bux applications that serve as integration tests for the compiler:

App	Description	Lines
boko-framework	Async web framework (like FastAPI), multi-threaded HTTP server	~660
jwt-pitbul	JWT CLI tool — sign, verify, decode (HS256/384/512, RS256/384/512, ES256/384, EdDSA)	~326
nexus	High-performance HTTP/1.1, HTTP/2 & WebSocket server	~550

The bootstrap compiler successfully parses and type-checks all three applications without hanging or crashing.

---

Documentation

• docs/LanguageRef.md — Language reference
• docs/Stdlib.md — Standard library documentation
• docs/BuildAndTest.md — Build and test guide
• PLAN.md — Roadmap to self-hosting

---

License

MIT