From a58c68c2cf4c7580ef7df37efe53181888c256a7 Mon Sep 17 00:00:00 2001
From: Chris Watson <cawatson1993@gmail.com>
Date: Mon, 9 Mar 2026 19:15:07 -0600
Subject: [PATCH 1/2] Resolve @VROOT to module root

---
 vlib/v/checker/checker.v                        |  6 ++++++
 vlib/v/tests/cflags/vmodroot_and_vroot_test.c.v | 12 ++++++++++++
 vlib/v/tests/cflags/vroot_obj.c                 |  3 +++
 vlib/v/tests/cflags/vroot_obj.h                 |  1 +
 4 files changed, 22 insertions(+)
 create mode 100644 vlib/v/tests/cflags/vroot_obj.c
 create mode 100644 vlib/v/tests/cflags/vroot_obj.h

diff --git a/vlib/v/checker/checker.v b/vlib/v/checker/checker.v
index a9b1ced7797e53..e7632f001f2fea 100644
--- a/vlib/v/checker/checker.v
+++ b/vlib/v/checker/checker.v
@@ -3155,6 +3155,12 @@ fn (mut c Checker) hash_stmt(mut node ast.HashStmt) {
 
 fn (mut c Checker) resolve_pseudo_variables(oflag string, pos token.Pos) ?string {
 	mut flag := oflag
+	if flag.contains('@VROOT') {
+		flag = util.resolve_vmodroot(flag.replace('@VROOT', '@VMODROOT'), c.file.path) or {
+			c.error(err.msg(), pos)
+			return none
+		}
+	}
 	if flag.contains('@VEXEROOT') {
 		// expand `@VEXEROOT` to its absolute path
 		flag = flag.replace('@VEXEROOT', c.pref.vroot)
diff --git a/vlib/v/tests/cflags/vmodroot_and_vroot_test.c.v b/vlib/v/tests/cflags/vmodroot_and_vroot_test.c.v
index 2413818e911730..d26da9b3f09735 100644
--- a/vlib/v/tests/cflags/vmodroot_and_vroot_test.c.v
+++ b/vlib/v/tests/cflags/vmodroot_and_vroot_test.c.v
@@ -11,8 +11,20 @@ fn C.add(i32, i32) i32
 #flag -I @VEXEROOT/thirdparty/stb_image
 #include "stb_image.h"
 
+// Tests that deprecated @VROOT still resolves to the current module root for object-file flags
+#flag @VROOT/vroot_obj.o
+#include "@VMODROOT/vroot_obj.h"
+
+fn C.meaning_of_life() i32
+
 fn test_vroot_and_vmodroot() {
 	x := C.add(123, 456)
 	dump(x)
 	assert x == 579
 }
+
+fn test_vroot_object_flags_resolve_to_module_root() {
+	x := C.meaning_of_life()
+	dump(x)
+	assert x == 42
+}
diff --git a/vlib/v/tests/cflags/vroot_obj.c b/vlib/v/tests/cflags/vroot_obj.c
new file mode 100644
index 00000000000000..8327a2f49b2ddc
--- /dev/null
+++ b/vlib/v/tests/cflags/vroot_obj.c
@@ -0,0 +1,3 @@
+int meaning_of_life(void) {
+	return 42;
+}
diff --git a/vlib/v/tests/cflags/vroot_obj.h b/vlib/v/tests/cflags/vroot_obj.h
new file mode 100644
index 00000000000000..3a6933b5ea45fd
--- /dev/null
+++ b/vlib/v/tests/cflags/vroot_obj.h
@@ -0,0 +1 @@
+int meaning_of_life(void);

From bfae05965315971b2970a3952c603dd946ceca5c Mon Sep 17 00:00:00 2001
From: Chris Watson <cawatson1993@gmail.com>
Date: Tue, 10 Mar 2026 12:43:42 -0600
Subject: [PATCH 2/2] tools: refresh vdoc external modules on rebuild

---
 vlib/v/util/util.v | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/vlib/v/util/util.v b/vlib/v/util/util.v
index 4a3f4d39096134..bc46eec7fe0f59 100644
--- a/vlib/v/util/util.v
+++ b/vlib/v/util/util.v
@@ -128,7 +128,9 @@ pub fn launch_tool(is_verbose bool, tool_name string, args []string) {
 	if should_compile {
 		emodules := external_module_dependencies_for_tool[tool_name]
 		for emodule in emodules {
-			check_module_is_installed(emodule, is_verbose, false) or { panic(err) }
+			// Refresh external tool modules during recompilation, so tools pick up upstream
+			// compatibility fixes even when an older checkout already exists locally.
+			check_module_is_installed(emodule, is_verbose, true) or { panic(err) }
 		}
 		mut compilation_command := '${os.quoted_path(vexe)} '
 		if tool_name in ['vself', 'vup', 'vdoctor', 'vsymlink'] {