From 1566df068f96d41c1a4e34ace6dc6f7107b0ff30 Mon Sep 17 00:00:00 2001
From: TermiNexus <wyt18222152539wyt@163.com>
Date: Fri, 2 Oct 2026 22:07:01 +0800
Subject: [PATCH] =?UTF-8?q?feat(stub):=20=E4=BB=A5=20viperbuild.vpnci=20?=
 =?UTF-8?q?=E6=9B=BF=E6=8D=A2=20project=5Fbuild.vpnci?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

viperbuild 是编译器内建宏库（与 t / c / ctraits 同级），存根仅供 Vipeye 解析；
文件名与 import 名保持一致，注释改为英文，并移除旧的 project_build.vpnci。
---
 project_build.vpnci |  2 --
 viperbuild.vpnci    | 56 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 2 deletions(-)
 delete mode 100644 project_build.vpnci
 create mode 100644 viperbuild.vpnci

diff --git a/project_build.vpnci b/project_build.vpnci
deleted file mode 100644
index e63bf36..0000000
--- a/project_build.vpnci
+++ /dev/null
@@ -1,2 +0,0 @@
-def make():
-    pass
\ No newline at end of file
diff --git a/viperbuild.vpnci b/viperbuild.vpnci
new file mode 100644
index 0000000..02a82d2
--- /dev/null
+++ b/viperbuild.vpnci
@@ -0,0 +1,56 @@
+"""viperbuild — Compile-time build configuration library
+
+viperbuild is a compiler built-in macro library that emits no runtime code.
+The compiler recognizes ``import viperbuild as vb`` inside the dependency
+closure of the entry file and extracts the build configuration from it
+(source dir / build root / compiler / linker / target triple, ...).
+
+This file is a ``.vpnci`` stub: it exists solely for Vipeye (the pyright-based
+VSCode Viper LSP) to provide static inference and completion. The compiler does
+not read it at all; the real macro semantics are implemented inside TransPyV.
+
+Constraints:
+- Only ONE Project object is allowed per dependency closure.
+- Project is a macro type: field assignments happen at compile time and
+  reading it (using it as an rvalue) is forbidden.
+- ``source`` defaults to the directory containing the entry file; when set
+  explicitly, the entry file must reside under it, otherwise it is fatal.
+"""
+
+
+class Project:
+    """Compile-time project object (macro type)."""
+
+    name: str
+    version: str
+    source: str
+    buildroot: str
+    includes: list[str]
+    compiler: list[str]
+    linker: list[str]
+    static_libs: list[str]
+    dynamic_libs: list[str]
+    output: str
+
+    def __init__(self, name: str, version: str = "") -> None:
+        """Construct a project object."""
+        pass
+
+    def config(self, source: str = "", buildroot: str = "",
+               includes: list[str] = [], compiler: list[str] = [],
+               linker: list[str] = [], static_libs: list[str] = [],
+               dynamic_libs: list[str] = [], output: str = "") -> None:
+        """Set multiple fields at once (equivalent to individual assignments)."""
+        pass
+
+    def build(self, triple: str = "", datalayout: str = "",
+              selfmachine: bool = False) -> None:
+        """Commit and trigger the build of this project.
+
+        triple + datalayout: explicit target platform (must be given as a pair).
+        selfmachine=True   : use the recommended values for the local machine
+                             (mutually exclusive with explicit triple/datalayout;
+                             giving both is fatal).
+        When neither is given, selfmachine defaults to True.
+        """
+        pass