Enhacnementsand toolchain

README.MD

@@ -1 +1,162 @@
-// SOON
+# vuurraaf/v
+
+A complete toolchain for **VuurRaaf**, written in V from scratch: a compiler,
+an assembler, a linker, and a stack-based runtime. Everything — including the
+object file format and the virtual machine — lives in this repository.
+
+```
+.vr  --compiler-->  .vobj  --linker-->  .vbin  --vm-->  output
+.vasm --assembler--> .vobj
+```
+
+## Build
+
+Requires [V](https://vlang.io) (`v` in your PATH).
+
+```bash
+v -o bin/vr .        # build the toolchain
+./bin/vr up          # or rebuild from inside the toolchain
+./bin/vr symlink     # optionally symlink bin/vr into your PATH
+```
+
+> Note: build with `v .` from the project root. Building via an explicit file
+> or path argument makes V pick tcc without the Boehm GC, a combination that
+> miscompiles this codebase (`vr up` already does the right thing).
+
+## Usage
+
+```
+vr compile <file.vr> [-o out.vobj]          source  -> object
+vr assemble <file.vasm> [-o out.vobj]       assembly -> object
+vr link <a.vobj> [more.vobj ...] [-o out]   objects -> executable (.vbin)
+vr run <file.vr|file.vbin>                  compile+link+run, or run a binary
+vr debug <file.vr|file.vbin>                run with an instruction trace
+vr test <file.vr>                           run every test_* function
+vr bench <file.vr> [iterations]             benchmark main()
+vr clean                                    remove .vobj/.vbin artifacts
+vr up                                       rebuild bin/vr
+vr symlink                                  link bin/vr into your PATH
+vr config [set <key> <value>]               toolchain config (outdir, verbose)
+vr info | loader | alloc | version | help
+```
+
+Quick start:
+
+```bash
+./bin/vr run examples/hello.vr        # run a program
+./bin/vr test examples/tests.vr       # run the tests (one fails on purpose)
+./bin/vr debug examples/hello.vr      # watch every bytecode instruction
+
+# the assembler path
+./bin/vr assemble examples/math.vasm -o math.vobj
+./bin/vr link math.vobj -o math.vbin
+./bin/vr run math.vbin
+
+# multi-file programs (functions in one file may call functions in another)
+./bin/vr compile examples/lib.vr -o lib.vobj
+./bin/vr compile examples/use_lib.vr -o use_lib.vobj
+./bin/vr link lib.vobj use_lib.vobj -o use_lib.vbin
+./bin/vr run use_lib.vbin
+```
+
+## The VuurRaaf language
+
+A small, V-flavored language. Everything is a 64-bit integer or a string
+(strings concatenate with `+` and compare with `==`/`!=`; `print`/`println`
+accept both).
+
+```
+fn greet(name) {
+    println("hello, " + name + "!")
+}
+
+fn fib(n) {
+    if n < 2 {
+        return n
+    }
+    return fib(n - 1) + fib(n - 2)
+}
+
+fn main() {
+    let x = 6 * 7                       // let with type inference
+    assert x == 42                       // checked by the vm at runtime
+    let big = x > 40 and x < 50          // and / or / not, short-circuiting
+    if big {
+        println("x is big")
+    } else {
+        println("x is small")
+    }
+    let i = 0
+    while i < 3 {
+        println("counting " + i)         // "counting 0", ...
+        i = i + 1
+    }
+    println(fib(10))                     // 55
+}
+```
+
+- functions: `fn name(a, b) { ... }` with `return expr`
+- variables: `let name = expr`, reassignment `name = expr`
+- operators: `+ - * / %`, `== != < <= > >=`, `and or not`, unary `-`
+- statements: `let`, assignment, `if/else`, `while`, `return`, `assert`, calls,
+  `print(...)` / `println(...)`
+- comments: `//`
+
+## Assembly
+
+`.vasm` files talk to the VM directly. Labels, `.global` exports, and the full
+opcode set:
+
+```
+; comment
+.global main
+main:
+    push_int 42
+    call helper 1        ; call <target> <argc>
+    println
+    halt
+
+.global helper
+helper:
+    enter 0              ; reserve extra locals (args were copied in by `call`)
+    load 0
+    retv
+```
+
+Opcodes: `halt push_int push_str load store pop dup add sub mul div mod neg
+eq ne lt le gt ge and or not jmp jz jnz call ret retv print println assert
+enter`.
+
+## Formats
+
+- **VROBJ** (`.vobj`) — linker input: bytecode, exported symbols (function
+  name -> code offset), string constants, and relocations (call sites and
+  string references).
+- **VRBIN** (`.vbin`) — the executable: function table, string table, bytecode.
+
+## Architecture
+
+| module       | role                                                        |
+|--------------|-------------------------------------------------------------|
+| `compiler/`  | lexer, recursive-descent parser, bytecode codegen (VROBJ)   |
+| `assembler/` | `.vasm` -> VROBJ                                            |
+| `linker/`    | resolves relocations, rebases strings, emits VRBIN          |
+| `vm/`        | stack VM: tagged values, call frames, string heap, tracing  |
+| `obj/`       | VROBJ/VRBIN binary formats                                  |
+| `bin/`       | small standalone tools: `tl_alloc.v`, `tl_loader.v`         |
+
+The VM is a stack machine with 64-bit tagged values (numbers are stored
+shifted left so no integer collides with a string handle). Calls push a frame
+(return address, base pointer, argc), copy arguments into local slots, and
+reserve extra locals with `enter n`. `vr debug` prints every instruction with
+the stack contents.
+
+## Repository layout
+
+```
+main.v               CLI entry point (vr <command> ...)
+v.mod                module definition
+compiler/ assembler/ linker/ vm/ obj/   the toolchain itself
+bin/                 built binary + standalone tools
+examples/            runnable examples (hello, lib, asm, tests, fib)
+```