From 012c8a0e16d1efa7b4ee5ec3ff3b5457e60bfd2d Mon Sep 17 00:00:00 2001
From: allexanderbergmns <socials@libregrad.pp.ua>
Date: Tue, 25 Aug 2026 14:47:59 +0200
Subject: [PATCH] Executable vrmm

---
 README.MD           | 25 +++++++++++++++++++++++++
 compiler/lexer.v    | 10 +++++++++-
 examples/build.vrmm |  2 ++
 main.v              | 17 +++++++++++++++++
 4 files changed, 53 insertions(+), 1 deletion(-)
 mode change 100644 => 100755 examples/build.vrmm

diff --git a/README.MD b/README.MD
index abd0430..6146072 100644
--- a/README.MD
+++ b/README.MD
@@ -106,6 +106,31 @@ A target that returns a nonzero integer, calls `exit(n)` with `n > 0`, or
 `throw`s fails the build. Paths are relative to the working directory;
 `build_root()` returns the module's own directory for absolute paths.
 
+### Running build modules as scripts
+
+A `.vrmm` (or `.vr`) file may start with a shebang line so it can be executed
+directly like any script — the toolchain skips the shebang when compiling, so
+error line numbers stay aligned with the file:
+
+```
+#!/usr/bin/env vr
+fn main() {
+    build_compile("main.vr", "main.vobj")
+    build_link(["main.vobj"], "main.vbin")
+}
+```
+
+```bash
+chmod +x build.vrmm
+./build.vrmm            # equivalent to: vr make
+./build.vrmm clean      # run the clean() target
+./build.vrmm deploy --prod
+```
+
+The kernel invokes `vr <script> [args...]`; the toolchain routes an existing
+`.vrmm` path to `vr make -f <file>` and an existing `.vr` path to
+`vr run <file>`, so `vr myprog.vr` also just works.
+
 Build builtins:
 
 | builtin | description |
diff --git a/compiler/lexer.v b/compiler/lexer.v
index 330356b..1066164 100644
--- a/compiler/lexer.v
+++ b/compiler/lexer.v
@@ -2,7 +2,15 @@
 module compiler
 
 pub fn tokenize(src string) ![]Tok {
-	mut l := Lexer{ src: src, line: 1 }
+	// a script may start with a shebang line (#!...) so it can be executed
+	// directly (e.g. `#!/usr/bin/env vr`). Drop it, but keep the trailing
+	// newline so error line numbers stay aligned with the file on disk.
+	mut s := src
+	if s.starts_with('#!') {
+		nl := s.index('\n') or { s.len }
+		s = s[nl..]
+	}
+	mut l := Lexer{ src: s, line: 1 }
 	mut toks := []Tok{}
 	for {
 		t := l.next()!
diff --git a/examples/build.vrmm b/examples/build.vrmm
old mode 100644
new mode 100755
index 8c68d24..48d5e14
--- a/examples/build.vrmm
+++ b/examples/build.vrmm
@@ -1,6 +1,8 @@
+#!/usr/bin/env vr
 // build.vrmm — a VuurRaaf Make Module: build instructions for the toolchain,
 // written in VuurRaaf itself (like V's .vsh, but for this language).
 //
+//   ./examples/build.vrmm                         run directly (after chmod +x)
 //   ./bin/vr make -f examples/build.vrmm          build + run hello
 //   ./bin/vr make -f examples/build.vrmm multi    compile/link/run a 2-file program
 //   ./bin/vr make -f examples/build.vrmm test     run tests.vr
diff --git a/main.v b/main.v
index 494e77e..f63f109 100644
--- a/main.v
+++ b/main.v
@@ -113,6 +113,21 @@ fn main() {
 			toolchain_unloader()
 		}
 		else {
+			// direct script execution — this is what makes shebangs work:
+			// `#!/usr/bin/env vr` has the kernel call `vr <script> [args...]`,
+			// so route an existing .vrmm/.vr file to make/run accordingly
+			if os.exists(cmd) && cmd.ends_with('.vrmm') {
+				mut m := ['-f', cmd]
+				m << args[1..]
+				toolchain_make(m) or { die('make', err) }
+				return
+			}
+			if os.exists(cmd) && cmd.ends_with('.vr') {
+				mut r := [cmd]
+				r << args[1..]
+				toolchain_run(r) or { die('run', err) }
+				return
+			}
 			eprintln('vr: unknown command "${cmd}"')
 			eprintln("run 'vr help' for usage")
 			exit(1)
@@ -183,6 +198,8 @@ fn toolchain_help() {
 	println('  make [target] [args...]                  run build.vrmm (target = main)')
 	println('  make -f <file.vrmm> [target] [args...]   run another build module (.vrmm)')
 	println('  build                                    alias for make')
+	println('  <script.vrmm> [target] [args...]         run a build module directly (shebang)')
+	println('  <file.vr> [args...]                      run a program directly (shebang)')
 	println('  clean                                    remove build artifacts')
 	println('  up                                       rebuild the vr binary into bin/')
 	println('  symlink                                  link bin/vr into your PATH')