Documentation
Buraaq 1.0 documentation
Install with winget, a Release zip, or the clone scripts. Write a banking CLI from a single println to a packed Keel service, then Stream, Hold, and Grid. Systems chapters come next. Then servers. Then shipping. Optional Windows UI is last in Systems: only if you need a native window.
Learn
Install via winget, zip, or scripts; ledger to API; Stream, Hold, Grid, Script, Mind.
- Installwinget, Release zip, or install.ps1 / install.sh.
- What 1.0 shipsSelf-hosted compiler, generics copies, dock, in-tree packages, Gate B numbers.
- Getting startedYour first .bq file. Unique std names import themselves. buraaq run.
- The language in one pageBindings, functions, generics copies, interpolation, auto-import.
- Guided: a banking CLIOne program from println to a packed Keel service.
- Numbers, text, and moneyTypes you use every day while recording deposits.
- Arrays and listsHold transactions in order. Index, append, length.
- Loops and decisionsif, while, for: compute a balance from the list.
- FunctionsName the operations: deposit, withdraw, print.
- StructsAccount and Transaction as real data, not loose variables.
- Errors you can seeInsufficient funds as a value, not an exception.
- Modules and packagesPath is the module. Auto-import unique std.*. In-tree packages/index.json.
- The ledger becomes an appSplit the CLI into modules, serve it on Keel, pack a ship.
- Standard libraryFiles, text, time, Stream, Hold, Grid: one obvious way.
- StreamLive frames. Not WebSockets. stream, wire, say, hear, clip, shot.
- GfxGame canvas and sound. canvas, ink, flip, held, play, tone.
- HoldNamed columns. Not Pandas. hold, stow, pick, keep.
- GridNumeric arrays. Not NumPy. zeros, dot, matmul.
- Testingtest blocks, expect, buraaq test.
- Scripting (optional)REPL, -e, and script: clang compiles the same language.
- Mind: learning pathBasic to advanced: AI basics, serve, train, deploy.
- AI basicsDoctor, inspect, chat, and std.ai.
- Serve modelsOpenAI-compatible API, streaming, status, metrics.
- Strata: heavy modelsGPU → RAM → NVMe residency when models outgrow VRAM.
- Train adaptersLoRA/QLoRA via managed venv (PEFT/TRL).
- Deploy AIai pack, ship preflight, land --ai checklist.
- If you know Python, C, or RustPython-shaped source, native machine code, no GC.
Systems
Ownership, allocation, measured Gate B loops, firmware, and how Buraaq stays fast without a GC.
- Systems programmingNo collector, predictable drop, C ABI, electronics on the metal.
- Ownership and borrowsOne owner. No lifetime annotations. The compiler tracks moves.
- Allocation and dropStack, new, scope exit. You do not free in safe code.
- Memory safetyGFA catches use-after-move and conflicting borrows.
- Unsafe and COne gate for MMIO, raw pointers, and FFI.
- Concurrencyspawn is an OS thread. Mutex and channel send/recv. Cancel is next.
- PerformanceGate B vs C++ -O2. integer_sum 0.00×. Worst case 1.02×.
- Electronics and embeddedstd.led and buraaq flash: blink a Pico W without CMake in your tree.
- Example: firmware loopHappy-path LED, then extern C when you outgrow the board pack.
- Example: kernel driver sketchHow a driver-shaped module stays small and explicit.
- Optional: native window (Lumen)If you need a Windows operator UI, Lumen is at the end of this track.
Servers
TLS services, REST, Postgres, and pages: sockets stay in the runtime.
- Servers and APIsKeel: declare pages and resources. run() binds TLS.
- Your first APIburaaq new, page, api, run. HTTP 8080, TLS 8443.
- REST in depthRoutes, JSON, health, CORS, limits.
- Pages and TLSStatic files, certificates, what belongs in source vs files.
- PostgresHow api() creates tables, host env, reconnect, libpq.
- CLI and editorsbuild, run, fmt, lsp, pack, ship, dock, add, index, debug.
Ship
Hashed native bundles, not Docker images. Pack once, dock, land.
- Shipping vs DockerA .bur is a hashed native binary plus its files. Not a guest OS.
- Pack and launchburaaq pack, up, launch. What lives inside the bundle.
- DockLive accept loop on :7422. Health, PUT, bearer token.
- Land on any hostAWS, Azure, GCP, Hetzner, or a rack.
- Advanced shippingSame-OS packs, env secrets, ports, rollback by hash.
- Security modelLegitimate use only. SHA-256, tokens, TLS. Administration cooperates with agencies.
50 chapters. Start at install.