企业官网建设流程全解析

• 语言运行时
• 编译器
• JIT编译
• 解释器
• 内存管理

导读

本指南围绕 V8 仓库中面向 Torque 文件（.tq）的工程规范，详解「新建.tq文件时必须注册到根目录BUILD.gn」这条核心规则：包括注册位置、字母序要求、条件编译块的写法，以及注册之后 Torque 编译器如何驱动代码生成的完整流程。读完本文，你将掌握在 V8 中新增一个 Torque 源文件的正确姿势，理解torque_files与v8_torque_files的区别，并能基于 BUILD.gn 的源码结构独立排查"新.tq文件未被编译"这类构建问题。

一、规则背景：什么是 Torque 与 .tq 文件

Torque 是 V8 用来编写内置函数（builtins）和运行期宏（runtime macros）的领域专用语言（DSL），它把类型化的高级语法编译为 V8 内部使用的 CodeStubAssembler（CSA）调用序列。V8 源码中所有.tq文件都集中在src/下，主要分布在两个目录：

• src/builtins/*.tq：内置函数实现，例如array.tq、promise-all.tq、string.tq；
• src/objects/*.tq：堆对象类型定义，例如js-objects.tq、string.tq、struct.tq；
• 另有少量测试与第三方文件，如test/torque/test-torque.tq和third_party/v8/builtins/array-sort.tq。

如果想深入了解 Torque 语法本身，可以继续阅读仓库内的 docs/torque/architecture.md 与 docs/torque/user-manual.md；本文聚焦的是工程层面的文件管理规范——新增一个.tq文件时，如何把它接入构建系统。

二、规则适用场景：何时触发本规范

规则文件agents/rules/torque.md通过 frontmatter 声明了自己的触发方式：

name: torque trigger: glob globs: src/**/*.tq

也就是说，只要工作内容涉及src/目录下的.tq文件（无论是 Agent 自动执行任务，还是开发者手工修改），就应遵循本规则。src/**/*.tq这一 glob 精确覆盖了src/builtins/、src/objects/、src/debug/、src/wasm/等所有子目录中的 Torque 源文件。

三、核心规则：新建 .tq 文件必须在 BUILD.gn 中注册

规则原文只讲了一件事，但这件事直接决定构建成败：

• 如果你创建了一个新的.tq文件，必须在根目录BUILD.gn中注册它。
• 定位BUILD.gn中的torque_files列表（注意：不是v8_torque_files）。
• 按字母顺序添加你的新文件路径。
• 注意：对现有文件的修改不需要任何注册变更。

拆解成三个要点：

1. 新建才需要注册，修改不需要。往已有.tq文件里加函数、改对象布局，都不需要动BUILD.gn；只有新增文件路径时才需要。
2. 注册目标是torque_files，而不是v8_torque_files。V8 构建系统中名称相似的变量很多，这条提示是为了避免新手把文件加到错误的位置。整个仓库中真正驱动 Torque 编译的列表就是根目录BUILD.gn里声明的torque_files。
3. 保持字母顺序。这既是为了 diff 可读性，也是为了避免重复冲突——V8 的代码审查工具（如 PRESUBMIT）通常也期望列表保持有序。

四、源码级验证：BUILD.gn 中的 torque_files 结构

打开根目录 BUILD.gn，torque_files列表从第 2183 行开始，可以看到它确实是严格按字母序排列的：

torque_files = [ "src/builtins/aggregate-error.tq", "src/builtins/array-at.tq", "src/builtins/array-concat.tq", "src/builtins/array-copywithin.tq", "src/builtins/array-every.tq", ... "src/objects/string.tq", "src/objects/struct.tq", ... "test/torque/test-torque.tq", "third_party/v8/builtins/array-sort.tq", ]

注意末尾两项：test/torque/test-torque.tq（Torque 自身的测试文件）和third_party/v8/builtins/array-sort.tq（第三方目录下的 Torque 文件），说明torque_files不仅收录src/下的文件，凡需要参与 Torque 编译的路径都在此列——这与规则中globs: src/**/*.tq的触发范围略有区别（后者只是规则的激活条件，不是注册范围的上限）。

4.1 条件注册：不同特性开关下的列表扩展

torque_files不只是静态列表，它还会依据 GN 构建参数按条件追加（见 BUILD.gn）：

if (v8_enable_i18n_support) { torque_files += [ "src/objects/intl-objects.tq", "src/objects/js-collator.tq", "src/objects/js-date-time-format.tq", ... ] } if (v8_enable_temporal_support) { torque_files += [ "src/objects/js-temporal-objects.tq" ] } if (v8_enable_webassembly) { torque_files += [ "src/builtins/js-to-wasm.tq", "src/builtins/wasm.tq", "src/builtins/wasm-strings.tq", "src/builtins/wasm-to-js.tq", "src/debug/debug-wasm-objects.tq", "src/wasm/wasm-objects.tq", ] if (v8_enable_drumbrake) { torque_files += [ "src/builtins/wasm-interpreter-wrappers.tq" ] } }

这给你一个重要启示：当你新增的.tq文件只与某一特性相关（如 i18n、Temporal、WebAssembly）时，应把它放进对应的条件块内，而不是无条件追加到基础列表。这样关闭该特性时，对应文件就不会被纳入编译，从而避免产生无谓的构建依赖或符号冲突。这些开关变量（v8_enable_i18n_support、v8_enable_temporal_support、v8_enable_webassembly、v8_enable_drumbrake）定义在 gni/v8.gni 中，属于 V8 构建的常规配置项。

五、注册之后发生了什么：Torque 代码生成流水线

把.tq文件加入torque_files后，构建系统会通过run_torque模板（见 BUILD.gn）驱动 Torque 编译器工作：

template("run_torque") { ... action("run_torque" + suffix) { deps = [ ":torque($toolchain)" ] # 先编译出 torque 可执行文件 script = "tools/run.py" sources = torque_files # 输入：所有 .tq 文件 destination_folder = "$target_gen_dir/torque-generated$suffix" ... args = [ "./" + rebase_path(... "/torque", root_build_dir), "-o", rebase_path("$destination_folder", root_build_dir), "-v8-root", rebase_path(".", root_build_dir), ] args += torque_files # 输出：逐个 .tq 生成对应代码 } }

从这段模板可以看到完整的调用链：

1. 先构建torque可执行程序（deps = [ ":torque($toolchain)" ]，Torque 编译器本身位于 src/torque/）；
2. 通过tools/run.py以所有torque_files为输入执行torque二进制；
3. 生成产物统一输出到$target_gen_dir/torque-generated/目录。

以src/objects/string.tq为例，一个.tq文件会派生出一组同名的生成文件（filetq = string_replace(file, ".tq", "-tq")，即把.tq替换为-tq）：

• string-tq-csa.cc/string-tq-csa.h：CSA 汇编器实现与声明；
• string-tq.cc：Torque 生成的运行时支持代码。

除此之外，run_torque还会统一生成一批全局头文件，包括builtin-definitions.h、instance-types.h、interface-descriptors.inc、exported-macros-assembler.h等（见 BUILD.gn），这些正是 V8 其它 C++ 代码#include的 Torque 生成接口。最终这些生成文件由torque_generated_initializers目标汇总编译进v8_base_without_compiler（见 BUILD.gn）。

结论：一个.tq文件如果不注册进torque_files，它就不会出现在run_torque的输入里，对应的*-tq-csa.cc/h等文件不会被生成，任何引用该 Torque 定义类型的 C++ 代码都会在编译阶段报"符号未定义"或"头文件缺失"错误。

六、实操清单：新增一个 .tq 文件的完整步骤

结合规则与源码，推荐按以下流程操作（以新增src/builtins/foo.tq为例）：

1. 创建文件：在src/builtins/下编写foo.tq，内容遵循 Torque 语法（参考docs/torque/user-manual.md）。
2. 确定注册位置：打开根目录 BUILD.gn，先判断新文件是否与某个特性开关绑定：
   • 通用功能 → 追加到torque_files基础列表（第 2183 行开始的块）；
   • 仅 i18n/Temporal/WebAssembly 相关 → 追加到对应的if条件块内。
3. 按字母序插入：在目标列表中找到新文件路径应处的排序位置，插入"src/builtins/foo.tq",（字符串带引号、行尾带逗号）。以array-at.tq、array-concat.tq的排布为参照。
4. 检查列表末尾的测试注册：若新增文件位于src/builtins/或src/objects/，通常还需确认它是否应出现在torque_files末尾的测试/第三方条目附近——一般只需保证列表整体有序即可。
5. 本地验证构建：重新运行 gn 生成与构建，确认out/<build_dir>/gen/torque-generated/foo-tq-csa.cc、foo-tq.cc等文件被生成，且编译通过。若文件未被生成，说明注册位置或拼写有误。
6. 提交前检查：修改已有.tq文件时，跳过 2～5 步，无需改动BUILD.gn。

七、常见误区与注意事项

• 误把文件加进v8_torque_files：仓库中确实存在v8_*前缀的相关变量（如v8_enable_*开关），但 Torque 文件列表的名字就是torque_files。规则特别强调这一点，就是为了防止混淆。
• 忘记字母顺序：虽然构建系统本身不校验顺序，但不按序插入会让后续合并冲突频繁，也容易在审查时被打回。
• 新建文件后未跑构建：注册本身是静态文本改动，只有重新执行 gn/ninja 才会触发run_torque重新生成代码；建议用ninja -C out/<build_dir> v8（或对应的d8目标）验证一次全量生成。
• 条件块归属错误：把 i18n 专属的.tq无条件加入基础列表，会导致v8_enable_i18n_support = false的构建中仍尝试编译该文件，进而因缺少 Intl 相关类型定义而失败。
• 只新增不注册的后果：Torque 生成代码缺失，症状往往是 C++ 侧#include "torque-generated/foo-tq-csa.h"报 file not found，或Undefined symbol链接错误，排查时应第一时间回到BUILD.gn确认注册。

结语

agents/rules/torque.md用三句话点出了 V8 中 Torque 文件管理的最小必要规范，而 BUILD.gn 中的torque_files列表及其run_torque流水线则从源码层面印证了这条规则的必要性：注册即编译，编译即生成，生成即被 C++ 引用。对任何在 V8 中新增 Torque 代码的开发者或 Agent 而言，牢记"新建注册、修改免注册、字母有序、条件归类"这十六个字，就能避免绝大多数与 Torque 相关的构建问题。

• 语言运行时
• 编译器
• JIT编译
• 解释器
• 内存管理