sbox InteropGen 的 .def 绑定描述文件格式全解析

s&box 引擎使用engine/Tools/InteropGen工具从.def文件生成 C++↔C# 双向互操作绑定代码。本文以 .def 文件格式文档 为主体，逐条讲解文件语法、顶层指令、include / inherit / skipall 组合机制与 manifest 清单，并结合仓库内真实 def 文件（如 engine.def、tools.def）与 GlobalParser.cs 源码，让你完整掌握如何阅读、编写与组织 binding set，并理解绑定集之间如何复用与排除定义。

一、.def 文件的基本语法规则

一个.def文件按行解析，规则非常简单：

• 空行被跳过，不产生任何语义；
• 以//开头的行是注释，同样被忽略；
• 其余每一行必然是以下三种之一：
  • 指令（directive）：行内第一个词是关键字，行内其余部分是它的参数；
  • 类型声明（type declaration）：如native class ...、managed struct ...等（详见 classes.md）；
  • 属性（attribute）：如[nogc]、[Handle:...]，作用于紧随其后的下一条声明。

值得注意的细节：

• 参数可以用双引号包裹，解析时引号会被剥离。例如ident "engine"与ident engine等价；
• 关键字不必位于行首：#include "foo.h"也能工作，因为解析器只匹配它找到的第一个"单词段"。这让 def 文件可以兼容 C++ 语法高亮——写#include时既满足了 C++ 高亮器，又被 InteropGen 识别为include指令。

这一解析行为在源码中有直接对应：GlobalParser.cs 中维护了一张Directives字典，把关键字映射到处理回调；ParseLine则依次尝试匹配native|managed类型声明正则、属性正则，最后才落到base.ParseLine处理通用指令。

二、顶层指令（Top-level directives）

下表完整列出了 def 文件可用的顶层指令：

以仓库中的真实文件 engine.def 为例，可以看到全部核心指令的典型组合：

ident "engine" nativedll engine2.dll exceptions "Sandbox.Interop.BindingException" namespace "Managed.SandboxEngine" cpp "../../src/engine2/interop.engine.cpp" hpp "../../src/engine2/interop.engine.h" cs "../Sandbox.Engine/Interop.Engine.cs" include "dbg.h" include "color.h" include "engine/*" include "tier3" include "common/*" include "resources"

注意其中ident、nativedll、exceptions、namespace、cs/cpp/hpp五类指令与文档描述一一对应，include则混合使用了头文件与文件夹两种形式。结合 Program.cs 可以看到这些指令的最终去向：cs决定ManagedWriter的输出路径，hpp/cpp决定NativeHeaderWriter与NativeWriter的输出路径，ident生成的igen_engine则是原生侧初始化导出符号。

另外从源码看，GlobalParser.cs 中的NativeDll处理还有一个细节：nativedll的参数会剥离扩展名并统一为/分隔的正向路径，也就是说nativedll engine2.dll实际记录为engine2，跨平台解析时再补上对应平台的扩展名。

三、include 指令的三种行为

include根据参数的不同，做三件完全不同的事：

1. 参数以.h结尾 → 头文件生成的原生头文件中会发出#include "..."。惯例写法是#include "vphysics2/iphysicsbody.h"，与include "vphysics2/iphysicsbody.h"解析结果完全相同——前者让你在 def 文件里写 C++ 风格代码时保持语法高亮正确。

2. 参数以.def结尾 → 内联解析该文件会被原地解析，如同其内容直接粘贴在当前位置。路径相对于包含它的文件（包括文件）解析。

3. 其他参数 → 当作文件夹目录下每一个*.def都按字母顺序包含进来；参数带尾随/*（如include "common/*"）时递归进入子文件夹。

哈希联动：被包含的 def 文本会计入本绑定集的定义哈希。这意味着任何被包含文件的改动都会正确使"二进制配对"失效——这是 s&box 防止原生/托管两侧二进制不同步的关键机制之一。

四、inherit 与 skipall：绑定集之间的复用与排除

当多个 def 覆盖同一段原生代码时，需要处理重复定义问题。仓库中tools.def构建在engine.def之上，正是文档所述模式的实例（见 tools.def）：

ident "tools" nativedll toolframework2.dll inherit "engine.def" include "tier3" include "common/*" // 与 engine.def 包含的文件夹相同 include "resources" include "tools/*"

inherit的语义：加载另一个 def 并记住它声明过什么。这里被继承 def 声明的类型仍然会被解析（两边 include 有意重叠，这样才能把那些类型作为参数和返回类型引用），但不会被重新发射——它们的包装器已经存在于被继承 def 的 assembly 中，并且会被排除在本 def 的导出表和结构体尺寸检查之外。

skipall的语义：当 def 继承链变得很深时使用更强力的形式。例如tools.hammer.def同时继承engine.def、tools.def、tools.assetsystem.def时：

inherit "tools.def" skipall "tools.def"

skipall的效果是：出现在被命名 def 中的一切——类（原生和托管）、结构体、以及它的.hinclude——在本 def 发射时全部跳过。inherit与skipall在源码中共享同一个加载路径：GlobalParser.cs 的LoadInto通过InteropPipeline.Build递归构建被引用 def，然后分别加入IncludedDefinitions或SkipAll列表；inherit只保留"可引用"，skipall则进一步影响SkipPolicy的发射决策。

从仓库的 manifest.def 可以看到这种层级结构：

Definitions/tools.def Definitions/tools.assetsystem.def Definitions/tools.hammer.def Definitions/tools.modeldoc.def Definitions/tools.animgraph.def Definitions/engine.def

tools.*系列 def 都通过inherit站在engine.def的肩膀上，共享同一套基础绑定，同时各自只发射自己独有的部分。

五、manifest.def：绑定集构建清单

engine/manifest.def（即 manifest.def）本质上只是一份待构建 def 的列表，每行一个：

Definitions/tools.def Definitions/engine.def ...

• 不以.def结尾的行会被忽略；
• 列表中的每个 def 会被并行处理。

这与 Program.cs 中的ProcessManifest实现完全对应：读取 manifest 后，用EndsWith(".def")过滤行、拼上 manifest 所在目录作为路径，然后为每个 defTask.Run一个ProcessDefinitionFile，全部完成后汇总成功状态。构建系统（Tools/SboxBuild）在仓库根目录调用Facepunch.InteropGen.Program.ProcessManifest( "engine" )，即驱动整个生成流程的入口。

六、输出与构建流程中的关键约束

把 def 与生成器联系起来，有几个工程上必须理解的事实：

• 生成产物不入库：cs/cpp/hpp指向的输出文件由构建时重新生成（仓库.gitignore排除了Interop.*.cs/interop.*），内容未变化的文件不会被重写；
• 两侧必须成对重建：原生导出表（casts、函数、变量 get/set）的槽位顺序在 C++ 与 C# 之间按索引匹配，统一由Writer/NativeExportTable.cs驱动，是槽位顺序的唯一权威来源；
• 哈希防错：运行时交换导出表时会校验 def 哈希，陈旧的二进制会快速失败，而不是运行到一半才崩；
• 改名会影响导出符号：mangled 名按遇到顺序用数字后缀去重碰撞，因此在 def 中重排类或成员可能重命名导出符号——两侧同时重新生成即可，这正是输出必须成对再生的原因。

引用路径提示：需要深入了解声明语法时，请继续阅读同目录的 classes.md（类、结构体、枚举、函数、变量与属性声明）和 types.md（参数类型、编组与out/ref/CastTo[...]等标志）；生成器的整体流程与项目布局可参见 InteropGen 文档索引。