2026/9/9 20:15:17
FEATURED · 精选文章 
V 语言编译器仓库协作开发指南读懂 AGENTS.md 的自举构建、测试体系与源码工作流【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in 1s with zero library dependencies. Supports automatic C V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/vVvlang.io是一个简单、快速、安全的编译型语言其编译器本身就是一个 V 程序。仓库根目录下的 AGENTS.md 是官方为 AI 编码代理也适合人类贡献者编写的实操速查手册覆盖从用make完成自举构建到编译器六个内部阶段、最小测试决策表、编译期特性边界的全部内容。阅读本文后你将掌握在 V 语言源码仓库中安全地构建./vnew、运行最小相关测试、遵循代码风格、排查代码生成问题的完整工作流并理解编译器内部模块的职责与对应源码路径。本文严格以 AGENTS.md 为主线以仓库中的 Makefile、编译器入口、vlib/v/ 目录结构与各类测试文件为佐证帮助你按官方口径把改代码 → 重建 → 跑测试 → 提交这条链路跑通。一、仓库定位与文档适用场景AGENTS.md 开篇自述为 Practical quick reference for the V compiler, standard library, and tools即针对V 编译器、标准库与配套工具的快速参考面向会读取、修改该仓库代码的 AI 代理编写但对人类同样适用。需要强调的是本指南是操作层面的规范它与仓库中另外两份文档形成互补关于整体贡献流程与提交信息约定见根目录的 CONTRIBUTING.md关于测试选择与输出期望的详细说明见 TESTS.md。当各文档规则出现冲突时AGENTS.md 明确规定以Build Rebuild、Testing、Reporting三节为准canonical其余章节向它们对齐。仓库关键目录一览后文会逐层展开路径内容vlib/V 标准库其中任何改动都可能影响编译器自身编译器是 V 程序cmd/v/v.v编译器主入口module maincmd/tools/vfmt、vdoc、vup、vquest、vcheck-md、vtest 等内置工具examples/示例程序含hello_world.v与编译期特性示例等thirdparty/打包的 C 库tcc、mbedtls、sokol 等vlib/v/编译器各阶段模块AST、parser、checker、gen 等二、三步快速上手Quick Start文档给出的从仓库根目录三步进入可工作状态流程如下仅当./v缺失时先构建一次执行makeWindows 平台用 makev.bat。构建一个可用的编译器推荐调试友好版./v -g -keepc -o ./vnew cmd/v之后所有操作都使用./vnew./vnew run examples/hello_world.v # 编译并运行 ./vnew -silent test vlib/v/ # 静默运行 vlib/v 下测试 ./vnew fmt -w path/to/file.v # 格式化为什么需要两步、两个编译器结合 Makefile 可以看清 V 的三段式自举bootstrap机制仓库里现有的./v是由 C 版本的 V 编译器vc/v.c经 Makefile 的download_vc目标拉取先生成v1、再由v1生成v2、最后由v2生成正式./v的产物。也就是说./v是母鸡用于孵化新的编译器而日常所有构建、运行、测试都应在./vnew上进行避免破坏这份可用的自举种子。这正是 AGENTS.md 中反复强调的./v与./vnew角色分工的根源。三、顶层规则与代理协作规范Top Rules / Agent Rules3.1 顶层的六条硬规则只用./v构建./vnew其他一切操作使用./vnew。所有 V 标志紧跟在./vnew之后、位于子命令/文件之前例如./vnew -g run file.v而非./vnew run file.v -g写在子命令之后的标志会被传递给该子命令。修改编译器或核心模块后重建./vnew。运行最小相关测试见 Testing 的触发条件。大型重构或大范围文件改动前先询问。除非明确要求不要 stash 或改动无关文件。3.2 Agent 的执行边界文档为代理规定了明确的可与不可仓库根目录是所有命令的默认工作目录文档示例路径为/opt/v实际环境可能不同若路径缺失用pwd核实后调整。输出风格默认简洁用短段落、列表与反引号命令组织内容语气偏严格操作型信息不足时直接提问。文件读写权限可以不经许可读写仓库内所有文件——但这只是文件访问而非变更范围对ci/或Dockerfile*如 Dockerfile、Dockerfile.alpine、Dockerfile.cross的任何编辑仍需显式询问。构建/测试/格式化可免许可执行属于校验步骤只有编辑范围需要询问运行fmt、定向测试或check-md不算变更。改动范围最小化只改用户请求所需的文件不做无关重构仅当需要修复其中的 bug 或直接支撑请求时才在正在触碰的代码内消除重复逻辑。thirdparty/默认不碰如需改动必须事先征求批准。必须询问的情形跨cmd/、vlib/、doc/、examples/多个顶层目录的大重构单个子系统内的大行为变更如 parser 规则、checker 解析、代码生成输出形态、诊断文本/顺序、工具 CLI 行为——大指用户可见的 CLI 标志、输出、诊断或 codegen 形状变化触碰ci/或Dockerfile*。例外纯文档类多文件改动无需询问但要在总结中说明。3.3 完整性与总结义务无法完成某一步时必须说明阻塞点、已尝试内容与剩余工作。实质性工作任何行为变更或超过一个文件的改动后应给出简短总结包含改动文件路径和已运行测试未运行需说明原因。绝不为了掩盖失败而修改测试只有行为变更是有意为之时才更新期望输出并在总结中写明理由。3.4 新增文件清单新增文件的默认要求用./vnew fmt -w格式化为公共函数补 V 文档注释格式// the_name does ...Markdown 文件运行./vnew check-md且每行不超过 100 字符引入新公共 API 时同步新增或更新测试。更深的边界情况参考 CONTRIBUTING.md 与 TESTS.md。四、安全红线不要弄坏仓库Safety由于./v是可用的自举编译器一旦被覆盖就可能让整个开发环境瘫痪。AGENTS.md 列出的安全规则是不要覆盖正在工作的./v二进制。绝不运行不带-o的./v self——否则会直接重写自身。正确姿势始终是./v -o ./vnew cmd/v之后所有检查都用./vnew。调试后端问题如 C 代码生成时保留生成的 C加-keepc。源码/Markdown 中避免隐藏或双向 Unicode 字符。编译器若已不可用按以下顺序恢复git stashmakegit stash applystash 前先git status确认不会隐藏无关工作只有明确指示或编译器损坏时才 stash。4.1 与仓库文档的差异处理仓库公开文档中的示例都写作v ...而本文档的工作环境约定用./v -g -keepc -o ./vnew cmd/v替代v self所有构建、运行、测试使用./vnewTESTS.md 建议 PR 前跑v test-all但在这里需要先询问再执行./vnew test-all。这些覆盖override是为了让代理工作流可复现并避免破坏自举编译器。五、快速决策表改动后该重建与测试什么AGENTS.md 提供了一张最小重建/测试决策表是日常开发中最常查阅的速查工具。表中命令省略了./vnew前缀实际执行时都要带上变更区域需要重建最少应跑的测试仅文档.md否check-md file.md编译器vlib/v/、cmd/v/是-silent vlib/v/compiler_errors_test.vtest vlib/v/核心模块builtin/strings/os/strconv/time是最小的相关测试仅 Parservlib/v/parser/是test vlib/v/parser/仅 Checkervlib/v/checker/是test vlib/v/checker/Comptimevlib/v/comptime/是test vlib/v/tests/comptime 相关测试vlib非编译器部分否最近的*_test.v或test vlib/path/工具cmd/tools/否工具专属测试否则最近的*_test.v诊断/输出变化是vlib/v/slow_tests/inout/compiler_test.vC 代码生成vlib/v/gen/c/是vlib/v/gen/c/coutput_test.v表格中的几个关键文件在仓库中都真实存在vlib/v/compiler_errors_test.v、vlib/v/gen/c/coutput_test.v、vlib/v/slow_tests/inout/compiler_test.v。注意两点cmd/v/属于编译器范畴REPL 与后端类变更还有额外触发条件见 Testing 一节。拿不准就先询问。六、通用工作流与变更报告Common Workflow / Reporting标准执行顺序开工前先git status确认./vnew存在必要时重建。编辑相关文件。若编译器源码或核心模块发生变化用./v -g -keepc -o ./vnew cmd/v重建./vnew。格式化被改动的.v/.vsh文件对改动的 Markdown 运行./vnew check-md。按变更范围运行最小相关测试。6.1 报告模板需要总结时必须包含行为变更或 No behavior change、已运行测试或说明未运行原因、被触碰的文件路径、是否存在无关改动、公共行为/工具输出变化时是否更新了文档。公共行为是否变化有明确判断标准编译输出、诊断、面向用户的 CLI、stdlib API包括面向开发者的标志、错误码或输出顺序变化都属于公共行为。内部重构且无公共行为变化则不需要更新文档。若公共行为或工具输出变化应同步更新对应位置的文档README.md 负责顶层 CLI 用法doc/负责编译器/工具文档tutorials/负责学习材料新增/变更公共 API 时更新模块文档或 README。CHANGELOG.md 与 ROADMAP.md 仅在明确要求时才更新。可接受的未跑测试理由包括纯文档改动、无相关测试、环境限制。纯文档改动跑./vnew check-md file.md即可若改了.out期望文件必须在总结中写明理由且只有当行为变更是有意为之时才允许更新。七、前置依赖与构建/重建Prerequisites / Build Rebuild7.1 工具链要求Unix 系make、git、一个 C 编译器clang或gcc。Windows使用 makev.bat 完成首次构建。7.2 构建与重建规则首次构建仅当./v缺失makeWindowsmakev.bat。构建./vnew调试友好代理工作流推荐./v -g -keepc -o ./vnew cmd/v绝不直接运行./v self只按上述命令构建./vnew。./v缺失 → 先make再建./vnew./vnew缺失但./v存在 → 运行./v -o ./vnew cmd/v。在 cmd/v/v.v 的main模块源码中可以看到编译器如何调度构建流程它导入v.pref、v.util、v.builder、v.builder.cbuilder等模块并在external_tools常量中注册了fmt、doc、test、test-all、check-md、vet、repl等全部子命令——这与 Makefile 中自举脚本、以及 AGENTS.md 的./vnew subcommand用法一一对应。7.3 重建触发条件必须重建./vnew的两种情形编译器源码vlib/v/或cmd/v/变更核心模块builtin、strings、os、strconv、time变更。理由在于这些核心模块会被编译器自身链接改动后旧的./vnew无法反映新行为。拿不准时重建./vnew总是更稳妥。7.4 常用构建标志速查标志作用-g调试信息V 行号-cg调试信息C 行号常与-keepc组合-keepc保留生成的 C 文件-prod优化构建-o file指定输出路径/文件名-cc clang选择 C 编译器-cstrict对生成的 C 采用更严格的标准-b js\|native\|wasm选择后端-os os交叉编译目标选择支持时八、运行程序与测试体系Run Programs / Testing8.1 编译与运行./vnew run file.v # 编译并运行 ./vnew file.v # 仅编译生成可执行文件 ./vnew -g run file.v # 带调试信息运行 ./vnew -keepc -cg run file.v # 调试运行C 行号 ./vnew run examples/hello_world.v # 仓库自带的经典示例8.2 测试运行方式./vnew path/to/file_test.v # 直接运行单个测试文件显示测试输出 ./vnew test path/to/file_test.v # 单文件仅测试运行器报告 ./vnew -silent test path/to/dir/ # 目录级只显示失败与汇总 ./vnew -stats test path/to/dir/ # 目录级附加统计/指标 ./vnew -silent vlib/v/compiler_errors_test.v # 编译器错误测试 VAUTOFIX1 ./vnew -silent vlib/v/compiler_errors_test.v # 自动修复 .out仅有意变更时 ./vnew test-all # 全量测试需先询问8.3 三类测试的形态标准单元测试*_test.v文件内定义test_开头的函数。输出对照测试vlib/v/slow_tests/inout/下的.vv源码与.out期望输出配对由 vlib/v/slow_tests/inout/compiler_test.v 驱动vlib/v/tests/下的用例可能使用.run.out期望用./vnew -silent test vlib/v/tests运行。这类精确匹配测试意味着任何空白字符变化都会导致失败——AGENTS.md 特别提醒Output tests require exact matches; whitespace changes break tests。8.4 按变更范围选择测试原则最局部化改动跑最小相关测试表格所列是最低限度而非上限跨切面改动要追加定向测试。典型映射如下编译器变更vlib/v/或cmd/v/./vnew -silent vlib/v/compiler_errors_test.v./vnew -silent test vlib/v/。仅 Parser./vnew -silent test vlib/v/parser/仅 Checker./vnew -silent test vlib/v/checker/。vlib 变更最近的*_test.v或./vnew -silent test vlib/path/。工具变更工具专属测试优先例如cmd/tools/vfmt对应vlib/v/fmt/fmt_test.vcmd/tools/vdoc对应cmd/tools/vdoc/vdoc_test.v。注意cmd/v/属于编译器范畴而非工具。诊断/输出变化./vnew -silent vlib/v/slow_tests/inout/compiler_test.v。C 代码生成变化./vnew -silent vlib/v/gen/c/coutput_test.v更严格的验证可用./vnew -cstrict -cc clang -silent test vlib/v/。REPL 变化./vnew -silent vlib/v/slow_tests/repl/repl_test.v。大范围重构./vnew -silent test-all。后端相关JS/native/WASM 后端尚不完整避免大范围-b backend test vlib/优先用定向*_test.v或小目录配合-b js|native|wasm运行。时间紧张时优先跑compiler_errors_test.v与最小定向测试输出或 codegen 可能受影响时再补跑compiler_test.v与coutput_test.v。更多选择策略与输出期望请见 TESTS.md。8.5 测试相关环境变量与标志VAUTOFIX1测试失败时自动更新.out需跑两次仅当行为变更有意时使用。VTEST_ONLYglob_pattern只运行匹配模式的测试。VTEST_HIDE_OK1隐藏成功测试只显示失败。./vnew -silent test path/to/dir/只显示失败项与汇总报告。-cc tcc有 TCC 时可加速测试构建。.out文件只在行为变更有意时才更新并须在总结中说明理由否则将不一致视为回归。九、代码风格Code Style注释仅在代码不易自明时补充简洁注释不要删除现有注释除非错误可修正语法或拼写而不改变含义。在新增/修改的每个公共函数或方法正上方添加 V 文档注释格式以函数名开头例如// the_name does ...。消灭复制粘贴存在重复逻辑时只有请求需要且在你已触碰的代码内才把重复代码提升为函数。unsafe{}最小化尽量避免unsafe块并压缩其作用域它只适合底层互操作C 指针转换、手动内存管理绝不应包裹普通 V 逻辑。必须使用时保持最小并添加解释性注释。Markdown 行长每行不超过 100 字符checker 检查严格至少对修改过的行生效。避免源码/Markdown 中出现隐藏或双向 Unicode 字符。非 V 文件保持原有格式vlib/v/slow_tests/inout/下的.vv文件视为测试夹具除非有意变更行为并更新期望输出否则不要格式化。格式化与检查命令见工具一节。十、模块、导入与互操作卫生10.1 Modules and ImportsV 的一条硬性约束模块名必须与其目录名一致module行不含层级不一致会导致静默导入失败silent import failures而import语句遵循目录层级例如import abc.def。这条规则在vlib/各模块目录的组织方式中随处可见——每个目录对应一个平级模块名。10.2 C/JS 互操作卫生避免在普通.v文件中直接使用C.或JS.符号应改用.c.v/.js.v后缀文件并可用-Wimpure-v标志捕获意外的杂质impurity。不要重构已有.v文件中正在工作的C./JS.用法除非确有必要必须改动时优先把互操作代码迁入.c.v/.js.v。重声明 C 函数时正确使用const_前缀有助于-cstrict与 C 静态分析工具。10.3 平台/后端专属代码的三种组织方式V 支持环境相关的文件后缀当整个文件都平台/后端相关时优先使用文件拆分后端拆分*.c.vC 后端、*.js.vJS 后端、*.native.vnative 后端、*.wasm.vWASM 后端。操作系统拆分*_windows.c.v、*_linux.c.v、*_nix.c.v以*_default.c.v兜底。编译标志拆分*_d_customflag.v仅在传-d customflag时包含*_notd_customflag.v仅在未传该标志时包含。规则约束不要使用组合式后缀如_d_flag_linux.c.v正确做法是_d_flag.v文件内配合$if linux {}对较小的平台差异直接用编译期$if块即可例如$if windows { ... } $else { ... }。十一、编译期代码与反射Compile-Time Code and ReflectionV 用$前缀标记编译期comptime操作它们由编译器求值而非运行时执行。AGENTS.md 特别指出AI 代理经常混淆 comptime 与 runtime 构造因此单独成节澄清边界。11.1 编译期$if$if在编译期求值不是运行时if用于平台、编译器与自定义标志判断$if windows { ... } $else $if linux { ... } $else { ... } $if debug { ... } // 由 -g 或 -cg 启用 $if prod { ... } // 由 -prod 启用 $if custom_flag ? { ... } // 由 -d custom_flag 启用两个高频错误一是平台相关代码误用运行时if——它引用非本平台符号时编译失败而$if会在不匹配平台直接整块剔除二是忘记自定义标志的?后缀——写成$if myflag { ... }时编译器把它当作内置选项并静默忽略只有$if myflag ? { ... }才正确匹配-d myflag。内置$if条件的完整清单可参考仓库中的编译期示例examples/compiletime/ 目录含reflection.v、methods.v、d_compile_value.v以及 vlib/v/comptime/ 的实现。11.2 编译期$for与类型元数据$for在编译期遍历类型元数据可作用于StructType.fields、StructType.methods、EnumType.values、StructType.attributes、SumType.variants、method.params。$for块内部用$if按字段/方法类型分支fn main() { $for field in MyStruct.fields { $if field.typ is string { println(field.name) } } }它也适用于泛型T.fields、param.fields配合fn genT {}。常见错误有三类用运行时for遍历结构体字段——不可行V 没有运行时反射必须用$for在$for m in Type.methods块之外调用obj.$method()——$method()仅在 comptime 方法遍历内合法以为 comptime$for生成运行时循环——并非如此编译器会把它逐字段/方法/变体展开为具体代码。11.3 受支持的编译期函数仅以下$前缀函数受支持$embed_file(path)把文件内容嵌入二进制。路径可为绝对路径、相对源文件的路径或使用VEXEROOT、VMODROOT等伪变量。$tmpl(path)编译 V 模板文件veb 使用。$env(VAR)编译期读取环境变量。$d(ident, default)读取编译期定义-d identvalue带默认值兜底。$res(path)嵌入资源Android。$compile_error(msg)产生编译期错误。$compile_warn(msg)产生编译期警告。$pkgconfig(name)编译期查询 pkg-config。$typeof(expr)、$sizeof(Type)、$isreftype(expr)、$__offsetof(Struct, field_name)、$dump(expr)均为无前缀形式typeof、sizeof、isreftype、__offsetof、dump的兼容别名。易错点新代码应优先使用不带$前缀的typeof、sizeof、isreftype、__offsetof、dump带$的别名也接受$embed_file返回的是EmbedFileData对象而非字符串需用.to_string()或.to_bytes()$env在编译期即固化运行期无法改变需要运行期取值应使用os.getenv二者不可混用。11.4 编译期伪变量前缀FN当前函数名。METHODReceiverType.MethodName。MOD当前模块名。STRUCT当前结构体名。FILE、DIR、LINE、COLUMN、FILE_LINE源码位置信息。LOCATION文件、行号与当前类型方法适合日志输出。VEXE、VEXEROOTV 编译器路径及其所在目录。VHASH、VCURRENTHASH编译器提交哈希。VMOD_FILE、VMODHASH、VMODROOT最近的v.mod信息v.mod 见仓库根目录 v.mod。BUILD_DATE、BUILD_TIME、BUILD_TIMESTAMP构建时间UTC可用环境变量SOURCE_DATE_EPOCH覆盖以实现可复现构建。OS、CCOMPILER、BACKEND、PLATFORM构建环境信息。11.5 编译期类型组Comptime 类型组把多类型归并为高层类型供泛型或 comptime$if判断$int全部整型、$float、$array、$map、$struct、$enum、$alias、$sumtype、$function、$interface、$option。用法示例$if field.typ is $int { ... }。11.6 comptime 变更与测试Comptime 逻辑位于 vlib/v/comptime/由 checker、parser 与 cgen 阶段共同执行。改动此处需重建./vnew并以./vnew -silent test vlib/v/tests/加上相关 comptime 定向测试验证。十二、调试方法论Debug观察 C 编译器行为-showcc打印 C 编译命令-show-c-output打印 C 编译器输出。构建带调试标志的临时编译器./vnew -o ./w -d trace_checker cmd/v ./w file.v保留并检视生成的 C-keepc -cg是常用组合-printfn name -o file.c只把命名的 C 函数输出到标准输出name采用modulename__fnname格式如main__main该标志可重复以打印多个函数。方法/泛型的 C 符号名更复杂可用-keepc确认准确符号。阶段追踪-d trace_scanner|trace_parser|trace_checker|trace_gen当某阶段提前停止时可定位问题。阶段计时-d time_parsing|time_checking。V panic-keepc -gC 段错误-keepc -cg -cc clang。JS/native/WASM 调试优先用-b js|native|wasm的小型聚焦测试文件必要时加-show-c-output避免大范围-b backend test vlib/。快速定位代码生成问题的技巧在相关代码生成点添加唯一注释标记如/*tom51*/重建并生成 C 后在新文件中搜索该标记即可把生成代码映射回准确的编译器源码位置——尤其适合多个代码路径输出相似代码、需确认实际命中路径的场景。文档给出了实例在 vlib/v/gen/c/assign.v 的生成代码中写入builtin___option_ok/*tom51*/((${styp}[]) {重建后在生成的 C 中搜索tom51即可确认该路径生效。问题修复后务必移除这些调试标记。十三、编译器架构Compiler Architecture13.1 编译流水线V 编译器的编译阶段由v.builder模块编排主链路为v.scanner → v.parser → v.checker → v.transformer → v.markused → v.gen.c各阶段对应目录均已存在于 vlib/v/ 下阶段目录职责scannervlib/v/scanner/词法分析tokenizertokenvlib/v/token/Token 定义parservlib/v/parser/由 token 生成 ASTcheckervlib/v/checker/类型检查与解析transformervlib/v/transformer/通用优化与简化让后端更简单markusedvlib/v/markused/死代码消除gen/cvlib/v/gen/c/C 代码生成主后端即 cgenAST 节点定义在 vlib/v/ast/格式化器在 vlib/v/fmt/。此外还有多个支撑性或可选子系统模块如v.comptime、v.generics、v.pref、v.reflection、v.callgraph等。编译器的多后端策略在 vlib/v/gen/ 下体现当前仓库中可见 Cgen/c/、JSgen/js/、WASMgen/wasm/三个后端目录。13.2 关键目录与测试位置速查vlib/标准库变更可能影响编译器自身。cmd/v/v.v编译器入口。cmd/tools/vfmt、vdoc、vup、vquest、vcheck-md、vtest 等工具。examples/示例程序。thirdparty/打包的 C 库。vlib/v/编译器模块ast/fmt/scanner/token/parser/checker/comptime/transformer/markused/gen 等。测试存放位置vlib/v/tests/编译器功能测试含 comptime。vlib/v/slow_tests/输出对照与慢测试。vlib/v/slow_tests/inout/输出对比测试.vv.out配对含comptime_*.vv等大量用例。vlib/v/parser/parser 错误测试。vlib/v/checker/checker 错误测试。vlib/v/gen/c/testdata/C 代码生成测试.vv.c.must_have。examples/compiletime/comptime 用法示例含reflection.v。十四、checker/parser 的错误上报机制在 vlib/v/checker/ 中诊断上报有三档核心 API 定义在 vlib/v/checker/errors.vc.error(message, pos)硬错误终止编译。c.warn(message, pos)警告允许继续编译。c.note(message, pos)仅信息提示。模式上大多数 checker 方法以fn (mut c Checker)作为接收者——这与 vlib/v/checker/checker.v 中Checker结构体的设计一致是整个类型检查子系统的方法约定。十五、Option/Result 类型语法?Type为可选值可为none!Type为结果类型可携带错误。常见 bug 集中在if 守卫中的解包、含 option 字段的结构体初始化、带 option 的三元表达式。修改 option/result 行为时需在 vlib/v/tests/ 添加回归测试测试文件可搜索该目录下与 option/result 相关的用例。实现侧陷阱三元表达式、SQL 语句与定长数组中的 option 需要在 cgen 中特殊处理相关生成逻辑位于 vlib/v/gen/c/。十六、工具链与提交规范16.1 工具命令格式化./vnew fmt -w file仅针对被改动的.v/.vsh文件新文件视为已改动文件同样需要格式化与 markdown 检查。全树格式检查./vnew -silent test-fmt仅在要求时或校验全树时运行。Markdown 检查./vnew check-md file.md被改动的.md文件在提交前必须通过。代码风格检查./vnew vet vlib/v仅在要求时或做大规模 checker 改动——vlib/v/checker/下超过 3 个文件——时运行。模块文档./vnew doc -readme -all -l module_name。检索rg pattern或git grep列文件rg --files。自动格式化钩子./vnew git-fmt-hook install。这些工具的真实源码位于 cmd/tools/例如 vfmt.v、vcheck-md.v、vtest-fmt.v、vvet/、vdoc/、vup.v 等印证了./vnew 子命令的分发机制对照 cmd/v/v.v 的external_tools常量列表。16.2 提交与 PR完整约定见 CONTRIBUTING.md原则是一个 commit 只含一个逻辑变更。分支分叉需要 rebase 或 merge 时不要未经询问就 force-push 或丢弃改动应向用户说明冲突并让其决定解决策略。倾向用git rebase保持线性历史但情况不明确时必须先询问。十七、环境变量一览变量作用VFLAGS向所有 V 调用传递标志如VFLAGS-g ./vnew test-allVEXEV 编译器可执行文件的路径CI/脚本中常用TMPDIR控制.tmp.c文件的写入位置V 使用TMPDIR/v/SOURCE_DATE_EPOCH覆盖构建时间戳以实现可复现构建影响BUILD_DATE、BUILD_TIME、BUILD_TIMESTAMPV2CC、V2CFLAGS、V2VERBOSEv2 开发专属对应仓库中 cmd/v/ 下的 V3/v2 相关文件十八、常见坑位清单Gotchas综合全文AGENTS.md 在结尾把高频坑收敛为一张清单这里逐条列出并标注依据核心模块会反向影响编译器builtin、strings、os、strconv、time改动后必须重建./vnew。模块名必须与目录名一致否则静默导入失败。源码中硬编码os.execute(v ...)的程序/工具会绕过./vnew工作流意外行为先检查是否调用了系统v。陈旧的./vnew会产生费解的失败行为异常时先重建。输出测试要求精确匹配空白变化即可破坏测试。C 编译报错时用-keepc检查生成的 C生成于/tmp/*.tmp.c路径受TMPDIR控制。编译期代码$if、$for、$embed_file等是 AI 犯错高发区先核对Compile-Time Code and Reflection一节的正确用法与陷阱。编译器损坏时按 Safety 节的恢复序列处理git stash→make→git stash apply。涉及新测试/测试基础设施变更、输出测试或.out更新、大范围重构、不确定慢测试运行器时查阅 CONTRIBUTING.md 与 TESTS.md。结语把 AGENTS.md 变成可执行的习惯AGENTS.md 的核心价值不在于罗列命令而在于它把V 编译器是自举的 V 程序这一事实转化为了一整套可复现的工作纪律./v只负责孵化./vnew、所有标志前置于子命令、核心模块变更必须重建、按决策表跑最小测试、损坏时走固定恢复序列。对任何想深入 V 编译器源码parser/checker/comptime/gen 各阶段或为标准库贡献代码的开发者而言先通读根目录的 AGENTS.md再结合 CONTRIBUTING.md、TESTS.md 与本仓库 vlib/v/、cmd/ 的源码结构就能以最低的试错成本进入稳定的开发循环。【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in 1s with zero library dependencies. Supports automatic C V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/v创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
V 语言编译器仓库协作开发指南：读懂 AGENTS.md 的自举构建、测试体系与源码工作流
V 语言编译器仓库协作开发指南读懂 AGENTS.md 的自举构建、测试体系与源码工作流【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in 1s with zero library dependencies. Supports automatic C V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/vVvlang.io是一个简单、快速、安全的编译型语言其编译器本身就是一个 V 程序。仓库根目录下的 AGENTS.md 是官方为 AI 编码代理也适合人类贡献者编写的实操速查手册覆盖从用make完成自举构建到编译器六个内部阶段、最小测试决策表、编译期特性边界的全部内容。阅读本文后你将掌握在 V 语言源码仓库中安全地构建./vnew、运行最小相关测试、遵循代码风格、排查代码生成问题的完整工作流并理解编译器内部模块的职责与对应源码路径。本文严格以 AGENTS.md 为主线以仓库中的 Makefile、编译器入口、vlib/v/ 目录结构与各类测试文件为佐证帮助你按官方口径把改代码 → 重建 → 跑测试 → 提交这条链路跑通。一、仓库定位与文档适用场景AGENTS.md 开篇自述为 Practical quick reference for the V compiler, standard library, and tools即针对V 编译器、标准库与配套工具的快速参考面向会读取、修改该仓库代码的 AI 代理编写但对人类同样适用。需要强调的是本指南是操作层面的规范它与仓库中另外两份文档形成互补关于整体贡献流程与提交信息约定见根目录的 CONTRIBUTING.md关于测试选择与输出期望的详细说明见 TESTS.md。当各文档规则出现冲突时AGENTS.md 明确规定以Build Rebuild、Testing、Reporting三节为准canonical其余章节向它们对齐。仓库关键目录一览后文会逐层展开路径内容vlib/V 标准库其中任何改动都可能影响编译器自身编译器是 V 程序cmd/v/v.v编译器主入口module maincmd/tools/vfmt、vdoc、vup、vquest、vcheck-md、vtest 等内置工具examples/示例程序含hello_world.v与编译期特性示例等thirdparty/打包的 C 库tcc、mbedtls、sokol 等vlib/v/编译器各阶段模块AST、parser、checker、gen 等二、三步快速上手Quick Start文档给出的从仓库根目录三步进入可工作状态流程如下仅当./v缺失时先构建一次执行makeWindows 平台用 makev.bat。构建一个可用的编译器推荐调试友好版./v -g -keepc -o ./vnew cmd/v之后所有操作都使用./vnew./vnew run examples/hello_world.v # 编译并运行 ./vnew -silent test vlib/v/ # 静默运行 vlib/v 下测试 ./vnew fmt -w path/to/file.v # 格式化为什么需要两步、两个编译器结合 Makefile 可以看清 V 的三段式自举bootstrap机制仓库里现有的./v是由 C 版本的 V 编译器vc/v.c经 Makefile 的download_vc目标拉取先生成v1、再由v1生成v2、最后由v2生成正式./v的产物。也就是说./v是母鸡用于孵化新的编译器而日常所有构建、运行、测试都应在./vnew上进行避免破坏这份可用的自举种子。这正是 AGENTS.md 中反复强调的./v与./vnew角色分工的根源。三、顶层规则与代理协作规范Top Rules / Agent Rules3.1 顶层的六条硬规则只用./v构建./vnew其他一切操作使用./vnew。所有 V 标志紧跟在./vnew之后、位于子命令/文件之前例如./vnew -g run file.v而非./vnew run file.v -g写在子命令之后的标志会被传递给该子命令。修改编译器或核心模块后重建./vnew。运行最小相关测试见 Testing 的触发条件。大型重构或大范围文件改动前先询问。除非明确要求不要 stash 或改动无关文件。3.2 Agent 的执行边界文档为代理规定了明确的可与不可仓库根目录是所有命令的默认工作目录文档示例路径为/opt/v实际环境可能不同若路径缺失用pwd核实后调整。输出风格默认简洁用短段落、列表与反引号命令组织内容语气偏严格操作型信息不足时直接提问。文件读写权限可以不经许可读写仓库内所有文件——但这只是文件访问而非变更范围对ci/或Dockerfile*如 Dockerfile、Dockerfile.alpine、Dockerfile.cross的任何编辑仍需显式询问。构建/测试/格式化可免许可执行属于校验步骤只有编辑范围需要询问运行fmt、定向测试或check-md不算变更。改动范围最小化只改用户请求所需的文件不做无关重构仅当需要修复其中的 bug 或直接支撑请求时才在正在触碰的代码内消除重复逻辑。thirdparty/默认不碰如需改动必须事先征求批准。必须询问的情形跨cmd/、vlib/、doc/、examples/多个顶层目录的大重构单个子系统内的大行为变更如 parser 规则、checker 解析、代码生成输出形态、诊断文本/顺序、工具 CLI 行为——大指用户可见的 CLI 标志、输出、诊断或 codegen 形状变化触碰ci/或Dockerfile*。例外纯文档类多文件改动无需询问但要在总结中说明。3.3 完整性与总结义务无法完成某一步时必须说明阻塞点、已尝试内容与剩余工作。实质性工作任何行为变更或超过一个文件的改动后应给出简短总结包含改动文件路径和已运行测试未运行需说明原因。绝不为了掩盖失败而修改测试只有行为变更是有意为之时才更新期望输出并在总结中写明理由。3.4 新增文件清单新增文件的默认要求用./vnew fmt -w格式化为公共函数补 V 文档注释格式// the_name does ...Markdown 文件运行./vnew check-md且每行不超过 100 字符引入新公共 API 时同步新增或更新测试。更深的边界情况参考 CONTRIBUTING.md 与 TESTS.md。四、安全红线不要弄坏仓库Safety由于./v是可用的自举编译器一旦被覆盖就可能让整个开发环境瘫痪。AGENTS.md 列出的安全规则是不要覆盖正在工作的./v二进制。绝不运行不带-o的./v self——否则会直接重写自身。正确姿势始终是./v -o ./vnew cmd/v之后所有检查都用./vnew。调试后端问题如 C 代码生成时保留生成的 C加-keepc。源码/Markdown 中避免隐藏或双向 Unicode 字符。编译器若已不可用按以下顺序恢复git stashmakegit stash applystash 前先git status确认不会隐藏无关工作只有明确指示或编译器损坏时才 stash。4.1 与仓库文档的差异处理仓库公开文档中的示例都写作v ...而本文档的工作环境约定用./v -g -keepc -o ./vnew cmd/v替代v self所有构建、运行、测试使用./vnewTESTS.md 建议 PR 前跑v test-all但在这里需要先询问再执行./vnew test-all。这些覆盖override是为了让代理工作流可复现并避免破坏自举编译器。五、快速决策表改动后该重建与测试什么AGENTS.md 提供了一张最小重建/测试决策表是日常开发中最常查阅的速查工具。表中命令省略了./vnew前缀实际执行时都要带上变更区域需要重建最少应跑的测试仅文档.md否check-md file.md编译器vlib/v/、cmd/v/是-silent vlib/v/compiler_errors_test.vtest vlib/v/核心模块builtin/strings/os/strconv/time是最小的相关测试仅 Parservlib/v/parser/是test vlib/v/parser/仅 Checkervlib/v/checker/是test vlib/v/checker/Comptimevlib/v/comptime/是test vlib/v/tests/comptime 相关测试vlib非编译器部分否最近的*_test.v或test vlib/path/工具cmd/tools/否工具专属测试否则最近的*_test.v诊断/输出变化是vlib/v/slow_tests/inout/compiler_test.vC 代码生成vlib/v/gen/c/是vlib/v/gen/c/coutput_test.v表格中的几个关键文件在仓库中都真实存在vlib/v/compiler_errors_test.v、vlib/v/gen/c/coutput_test.v、vlib/v/slow_tests/inout/compiler_test.v。注意两点cmd/v/属于编译器范畴REPL 与后端类变更还有额外触发条件见 Testing 一节。拿不准就先询问。六、通用工作流与变更报告Common Workflow / Reporting标准执行顺序开工前先git status确认./vnew存在必要时重建。编辑相关文件。若编译器源码或核心模块发生变化用./v -g -keepc -o ./vnew cmd/v重建./vnew。格式化被改动的.v/.vsh文件对改动的 Markdown 运行./vnew check-md。按变更范围运行最小相关测试。6.1 报告模板需要总结时必须包含行为变更或 No behavior change、已运行测试或说明未运行原因、被触碰的文件路径、是否存在无关改动、公共行为/工具输出变化时是否更新了文档。公共行为是否变化有明确判断标准编译输出、诊断、面向用户的 CLI、stdlib API包括面向开发者的标志、错误码或输出顺序变化都属于公共行为。内部重构且无公共行为变化则不需要更新文档。若公共行为或工具输出变化应同步更新对应位置的文档README.md 负责顶层 CLI 用法doc/负责编译器/工具文档tutorials/负责学习材料新增/变更公共 API 时更新模块文档或 README。CHANGELOG.md 与 ROADMAP.md 仅在明确要求时才更新。可接受的未跑测试理由包括纯文档改动、无相关测试、环境限制。纯文档改动跑./vnew check-md file.md即可若改了.out期望文件必须在总结中写明理由且只有当行为变更是有意为之时才允许更新。七、前置依赖与构建/重建Prerequisites / Build Rebuild7.1 工具链要求Unix 系make、git、一个 C 编译器clang或gcc。Windows使用 makev.bat 完成首次构建。7.2 构建与重建规则首次构建仅当./v缺失makeWindowsmakev.bat。构建./vnew调试友好代理工作流推荐./v -g -keepc -o ./vnew cmd/v绝不直接运行./v self只按上述命令构建./vnew。./v缺失 → 先make再建./vnew./vnew缺失但./v存在 → 运行./v -o ./vnew cmd/v。在 cmd/v/v.v 的main模块源码中可以看到编译器如何调度构建流程它导入v.pref、v.util、v.builder、v.builder.cbuilder等模块并在external_tools常量中注册了fmt、doc、test、test-all、check-md、vet、repl等全部子命令——这与 Makefile 中自举脚本、以及 AGENTS.md 的./vnew subcommand用法一一对应。7.3 重建触发条件必须重建./vnew的两种情形编译器源码vlib/v/或cmd/v/变更核心模块builtin、strings、os、strconv、time变更。理由在于这些核心模块会被编译器自身链接改动后旧的./vnew无法反映新行为。拿不准时重建./vnew总是更稳妥。7.4 常用构建标志速查标志作用-g调试信息V 行号-cg调试信息C 行号常与-keepc组合-keepc保留生成的 C 文件-prod优化构建-o file指定输出路径/文件名-cc clang选择 C 编译器-cstrict对生成的 C 采用更严格的标准-b js\|native\|wasm选择后端-os os交叉编译目标选择支持时八、运行程序与测试体系Run Programs / Testing8.1 编译与运行./vnew run file.v # 编译并运行 ./vnew file.v # 仅编译生成可执行文件 ./vnew -g run file.v # 带调试信息运行 ./vnew -keepc -cg run file.v # 调试运行C 行号 ./vnew run examples/hello_world.v # 仓库自带的经典示例8.2 测试运行方式./vnew path/to/file_test.v # 直接运行单个测试文件显示测试输出 ./vnew test path/to/file_test.v # 单文件仅测试运行器报告 ./vnew -silent test path/to/dir/ # 目录级只显示失败与汇总 ./vnew -stats test path/to/dir/ # 目录级附加统计/指标 ./vnew -silent vlib/v/compiler_errors_test.v # 编译器错误测试 VAUTOFIX1 ./vnew -silent vlib/v/compiler_errors_test.v # 自动修复 .out仅有意变更时 ./vnew test-all # 全量测试需先询问8.3 三类测试的形态标准单元测试*_test.v文件内定义test_开头的函数。输出对照测试vlib/v/slow_tests/inout/下的.vv源码与.out期望输出配对由 vlib/v/slow_tests/inout/compiler_test.v 驱动vlib/v/tests/下的用例可能使用.run.out期望用./vnew -silent test vlib/v/tests运行。这类精确匹配测试意味着任何空白字符变化都会导致失败——AGENTS.md 特别提醒Output tests require exact matches; whitespace changes break tests。8.4 按变更范围选择测试原则最局部化改动跑最小相关测试表格所列是最低限度而非上限跨切面改动要追加定向测试。典型映射如下编译器变更vlib/v/或cmd/v/./vnew -silent vlib/v/compiler_errors_test.v./vnew -silent test vlib/v/。仅 Parser./vnew -silent test vlib/v/parser/仅 Checker./vnew -silent test vlib/v/checker/。vlib 变更最近的*_test.v或./vnew -silent test vlib/path/。工具变更工具专属测试优先例如cmd/tools/vfmt对应vlib/v/fmt/fmt_test.vcmd/tools/vdoc对应cmd/tools/vdoc/vdoc_test.v。注意cmd/v/属于编译器范畴而非工具。诊断/输出变化./vnew -silent vlib/v/slow_tests/inout/compiler_test.v。C 代码生成变化./vnew -silent vlib/v/gen/c/coutput_test.v更严格的验证可用./vnew -cstrict -cc clang -silent test vlib/v/。REPL 变化./vnew -silent vlib/v/slow_tests/repl/repl_test.v。大范围重构./vnew -silent test-all。后端相关JS/native/WASM 后端尚不完整避免大范围-b backend test vlib/优先用定向*_test.v或小目录配合-b js|native|wasm运行。时间紧张时优先跑compiler_errors_test.v与最小定向测试输出或 codegen 可能受影响时再补跑compiler_test.v与coutput_test.v。更多选择策略与输出期望请见 TESTS.md。8.5 测试相关环境变量与标志VAUTOFIX1测试失败时自动更新.out需跑两次仅当行为变更有意时使用。VTEST_ONLYglob_pattern只运行匹配模式的测试。VTEST_HIDE_OK1隐藏成功测试只显示失败。./vnew -silent test path/to/dir/只显示失败项与汇总报告。-cc tcc有 TCC 时可加速测试构建。.out文件只在行为变更有意时才更新并须在总结中说明理由否则将不一致视为回归。九、代码风格Code Style注释仅在代码不易自明时补充简洁注释不要删除现有注释除非错误可修正语法或拼写而不改变含义。在新增/修改的每个公共函数或方法正上方添加 V 文档注释格式以函数名开头例如// the_name does ...。消灭复制粘贴存在重复逻辑时只有请求需要且在你已触碰的代码内才把重复代码提升为函数。unsafe{}最小化尽量避免unsafe块并压缩其作用域它只适合底层互操作C 指针转换、手动内存管理绝不应包裹普通 V 逻辑。必须使用时保持最小并添加解释性注释。Markdown 行长每行不超过 100 字符checker 检查严格至少对修改过的行生效。避免源码/Markdown 中出现隐藏或双向 Unicode 字符。非 V 文件保持原有格式vlib/v/slow_tests/inout/下的.vv文件视为测试夹具除非有意变更行为并更新期望输出否则不要格式化。格式化与检查命令见工具一节。十、模块、导入与互操作卫生10.1 Modules and ImportsV 的一条硬性约束模块名必须与其目录名一致module行不含层级不一致会导致静默导入失败silent import failures而import语句遵循目录层级例如import abc.def。这条规则在vlib/各模块目录的组织方式中随处可见——每个目录对应一个平级模块名。10.2 C/JS 互操作卫生避免在普通.v文件中直接使用C.或JS.符号应改用.c.v/.js.v后缀文件并可用-Wimpure-v标志捕获意外的杂质impurity。不要重构已有.v文件中正在工作的C./JS.用法除非确有必要必须改动时优先把互操作代码迁入.c.v/.js.v。重声明 C 函数时正确使用const_前缀有助于-cstrict与 C 静态分析工具。10.3 平台/后端专属代码的三种组织方式V 支持环境相关的文件后缀当整个文件都平台/后端相关时优先使用文件拆分后端拆分*.c.vC 后端、*.js.vJS 后端、*.native.vnative 后端、*.wasm.vWASM 后端。操作系统拆分*_windows.c.v、*_linux.c.v、*_nix.c.v以*_default.c.v兜底。编译标志拆分*_d_customflag.v仅在传-d customflag时包含*_notd_customflag.v仅在未传该标志时包含。规则约束不要使用组合式后缀如_d_flag_linux.c.v正确做法是_d_flag.v文件内配合$if linux {}对较小的平台差异直接用编译期$if块即可例如$if windows { ... } $else { ... }。十一、编译期代码与反射Compile-Time Code and ReflectionV 用$前缀标记编译期comptime操作它们由编译器求值而非运行时执行。AGENTS.md 特别指出AI 代理经常混淆 comptime 与 runtime 构造因此单独成节澄清边界。11.1 编译期$if$if在编译期求值不是运行时if用于平台、编译器与自定义标志判断$if windows { ... } $else $if linux { ... } $else { ... } $if debug { ... } // 由 -g 或 -cg 启用 $if prod { ... } // 由 -prod 启用 $if custom_flag ? { ... } // 由 -d custom_flag 启用两个高频错误一是平台相关代码误用运行时if——它引用非本平台符号时编译失败而$if会在不匹配平台直接整块剔除二是忘记自定义标志的?后缀——写成$if myflag { ... }时编译器把它当作内置选项并静默忽略只有$if myflag ? { ... }才正确匹配-d myflag。内置$if条件的完整清单可参考仓库中的编译期示例examples/compiletime/ 目录含reflection.v、methods.v、d_compile_value.v以及 vlib/v/comptime/ 的实现。11.2 编译期$for与类型元数据$for在编译期遍历类型元数据可作用于StructType.fields、StructType.methods、EnumType.values、StructType.attributes、SumType.variants、method.params。$for块内部用$if按字段/方法类型分支fn main() { $for field in MyStruct.fields { $if field.typ is string { println(field.name) } } }它也适用于泛型T.fields、param.fields配合fn genT {}。常见错误有三类用运行时for遍历结构体字段——不可行V 没有运行时反射必须用$for在$for m in Type.methods块之外调用obj.$method()——$method()仅在 comptime 方法遍历内合法以为 comptime$for生成运行时循环——并非如此编译器会把它逐字段/方法/变体展开为具体代码。11.3 受支持的编译期函数仅以下$前缀函数受支持$embed_file(path)把文件内容嵌入二进制。路径可为绝对路径、相对源文件的路径或使用VEXEROOT、VMODROOT等伪变量。$tmpl(path)编译 V 模板文件veb 使用。$env(VAR)编译期读取环境变量。$d(ident, default)读取编译期定义-d identvalue带默认值兜底。$res(path)嵌入资源Android。$compile_error(msg)产生编译期错误。$compile_warn(msg)产生编译期警告。$pkgconfig(name)编译期查询 pkg-config。$typeof(expr)、$sizeof(Type)、$isreftype(expr)、$__offsetof(Struct, field_name)、$dump(expr)均为无前缀形式typeof、sizeof、isreftype、__offsetof、dump的兼容别名。易错点新代码应优先使用不带$前缀的typeof、sizeof、isreftype、__offsetof、dump带$的别名也接受$embed_file返回的是EmbedFileData对象而非字符串需用.to_string()或.to_bytes()$env在编译期即固化运行期无法改变需要运行期取值应使用os.getenv二者不可混用。11.4 编译期伪变量前缀FN当前函数名。METHODReceiverType.MethodName。MOD当前模块名。STRUCT当前结构体名。FILE、DIR、LINE、COLUMN、FILE_LINE源码位置信息。LOCATION文件、行号与当前类型方法适合日志输出。VEXE、VEXEROOTV 编译器路径及其所在目录。VHASH、VCURRENTHASH编译器提交哈希。VMOD_FILE、VMODHASH、VMODROOT最近的v.mod信息v.mod 见仓库根目录 v.mod。BUILD_DATE、BUILD_TIME、BUILD_TIMESTAMP构建时间UTC可用环境变量SOURCE_DATE_EPOCH覆盖以实现可复现构建。OS、CCOMPILER、BACKEND、PLATFORM构建环境信息。11.5 编译期类型组Comptime 类型组把多类型归并为高层类型供泛型或 comptime$if判断$int全部整型、$float、$array、$map、$struct、$enum、$alias、$sumtype、$function、$interface、$option。用法示例$if field.typ is $int { ... }。11.6 comptime 变更与测试Comptime 逻辑位于 vlib/v/comptime/由 checker、parser 与 cgen 阶段共同执行。改动此处需重建./vnew并以./vnew -silent test vlib/v/tests/加上相关 comptime 定向测试验证。十二、调试方法论Debug观察 C 编译器行为-showcc打印 C 编译命令-show-c-output打印 C 编译器输出。构建带调试标志的临时编译器./vnew -o ./w -d trace_checker cmd/v ./w file.v保留并检视生成的 C-keepc -cg是常用组合-printfn name -o file.c只把命名的 C 函数输出到标准输出name采用modulename__fnname格式如main__main该标志可重复以打印多个函数。方法/泛型的 C 符号名更复杂可用-keepc确认准确符号。阶段追踪-d trace_scanner|trace_parser|trace_checker|trace_gen当某阶段提前停止时可定位问题。阶段计时-d time_parsing|time_checking。V panic-keepc -gC 段错误-keepc -cg -cc clang。JS/native/WASM 调试优先用-b js|native|wasm的小型聚焦测试文件必要时加-show-c-output避免大范围-b backend test vlib/。快速定位代码生成问题的技巧在相关代码生成点添加唯一注释标记如/*tom51*/重建并生成 C 后在新文件中搜索该标记即可把生成代码映射回准确的编译器源码位置——尤其适合多个代码路径输出相似代码、需确认实际命中路径的场景。文档给出了实例在 vlib/v/gen/c/assign.v 的生成代码中写入builtin___option_ok/*tom51*/((${styp}[]) {重建后在生成的 C 中搜索tom51即可确认该路径生效。问题修复后务必移除这些调试标记。十三、编译器架构Compiler Architecture13.1 编译流水线V 编译器的编译阶段由v.builder模块编排主链路为v.scanner → v.parser → v.checker → v.transformer → v.markused → v.gen.c各阶段对应目录均已存在于 vlib/v/ 下阶段目录职责scannervlib/v/scanner/词法分析tokenizertokenvlib/v/token/Token 定义parservlib/v/parser/由 token 生成 ASTcheckervlib/v/checker/类型检查与解析transformervlib/v/transformer/通用优化与简化让后端更简单markusedvlib/v/markused/死代码消除gen/cvlib/v/gen/c/C 代码生成主后端即 cgenAST 节点定义在 vlib/v/ast/格式化器在 vlib/v/fmt/。此外还有多个支撑性或可选子系统模块如v.comptime、v.generics、v.pref、v.reflection、v.callgraph等。编译器的多后端策略在 vlib/v/gen/ 下体现当前仓库中可见 Cgen/c/、JSgen/js/、WASMgen/wasm/三个后端目录。13.2 关键目录与测试位置速查vlib/标准库变更可能影响编译器自身。cmd/v/v.v编译器入口。cmd/tools/vfmt、vdoc、vup、vquest、vcheck-md、vtest 等工具。examples/示例程序。thirdparty/打包的 C 库。vlib/v/编译器模块ast/fmt/scanner/token/parser/checker/comptime/transformer/markused/gen 等。测试存放位置vlib/v/tests/编译器功能测试含 comptime。vlib/v/slow_tests/输出对照与慢测试。vlib/v/slow_tests/inout/输出对比测试.vv.out配对含comptime_*.vv等大量用例。vlib/v/parser/parser 错误测试。vlib/v/checker/checker 错误测试。vlib/v/gen/c/testdata/C 代码生成测试.vv.c.must_have。examples/compiletime/comptime 用法示例含reflection.v。十四、checker/parser 的错误上报机制在 vlib/v/checker/ 中诊断上报有三档核心 API 定义在 vlib/v/checker/errors.vc.error(message, pos)硬错误终止编译。c.warn(message, pos)警告允许继续编译。c.note(message, pos)仅信息提示。模式上大多数 checker 方法以fn (mut c Checker)作为接收者——这与 vlib/v/checker/checker.v 中Checker结构体的设计一致是整个类型检查子系统的方法约定。十五、Option/Result 类型语法?Type为可选值可为none!Type为结果类型可携带错误。常见 bug 集中在if 守卫中的解包、含 option 字段的结构体初始化、带 option 的三元表达式。修改 option/result 行为时需在 vlib/v/tests/ 添加回归测试测试文件可搜索该目录下与 option/result 相关的用例。实现侧陷阱三元表达式、SQL 语句与定长数组中的 option 需要在 cgen 中特殊处理相关生成逻辑位于 vlib/v/gen/c/。十六、工具链与提交规范16.1 工具命令格式化./vnew fmt -w file仅针对被改动的.v/.vsh文件新文件视为已改动文件同样需要格式化与 markdown 检查。全树格式检查./vnew -silent test-fmt仅在要求时或校验全树时运行。Markdown 检查./vnew check-md file.md被改动的.md文件在提交前必须通过。代码风格检查./vnew vet vlib/v仅在要求时或做大规模 checker 改动——vlib/v/checker/下超过 3 个文件——时运行。模块文档./vnew doc -readme -all -l module_name。检索rg pattern或git grep列文件rg --files。自动格式化钩子./vnew git-fmt-hook install。这些工具的真实源码位于 cmd/tools/例如 vfmt.v、vcheck-md.v、vtest-fmt.v、vvet/、vdoc/、vup.v 等印证了./vnew 子命令的分发机制对照 cmd/v/v.v 的external_tools常量列表。16.2 提交与 PR完整约定见 CONTRIBUTING.md原则是一个 commit 只含一个逻辑变更。分支分叉需要 rebase 或 merge 时不要未经询问就 force-push 或丢弃改动应向用户说明冲突并让其决定解决策略。倾向用git rebase保持线性历史但情况不明确时必须先询问。十七、环境变量一览变量作用VFLAGS向所有 V 调用传递标志如VFLAGS-g ./vnew test-allVEXEV 编译器可执行文件的路径CI/脚本中常用TMPDIR控制.tmp.c文件的写入位置V 使用TMPDIR/v/SOURCE_DATE_EPOCH覆盖构建时间戳以实现可复现构建影响BUILD_DATE、BUILD_TIME、BUILD_TIMESTAMPV2CC、V2CFLAGS、V2VERBOSEv2 开发专属对应仓库中 cmd/v/ 下的 V3/v2 相关文件十八、常见坑位清单Gotchas综合全文AGENTS.md 在结尾把高频坑收敛为一张清单这里逐条列出并标注依据核心模块会反向影响编译器builtin、strings、os、strconv、time改动后必须重建./vnew。模块名必须与目录名一致否则静默导入失败。源码中硬编码os.execute(v ...)的程序/工具会绕过./vnew工作流意外行为先检查是否调用了系统v。陈旧的./vnew会产生费解的失败行为异常时先重建。输出测试要求精确匹配空白变化即可破坏测试。C 编译报错时用-keepc检查生成的 C生成于/tmp/*.tmp.c路径受TMPDIR控制。编译期代码$if、$for、$embed_file等是 AI 犯错高发区先核对Compile-Time Code and Reflection一节的正确用法与陷阱。编译器损坏时按 Safety 节的恢复序列处理git stash→make→git stash apply。涉及新测试/测试基础设施变更、输出测试或.out更新、大范围重构、不确定慢测试运行器时查阅 CONTRIBUTING.md 与 TESTS.md。结语把 AGENTS.md 变成可执行的习惯AGENTS.md 的核心价值不在于罗列命令而在于它把V 编译器是自举的 V 程序这一事实转化为了一整套可复现的工作纪律./v只负责孵化./vnew、所有标志前置于子命令、核心模块变更必须重建、按决策表跑最小测试、损坏时走固定恢复序列。对任何想深入 V 编译器源码parser/checker/comptime/gen 各阶段或为标准库贡献代码的开发者而言先通读根目录的 AGENTS.md再结合 CONTRIBUTING.md、TESTS.md 与本仓库 vlib/v/、cmd/ 的源码结构就能以最低的试错成本进入稳定的开发循环。【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in 1s with zero library dependencies. Supports automatic C V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/v创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
