re_types_builder

是 rerun 系列crate的一部分。

此crate实现了Rerun的代码生成工具。

这些工具将语言无关的 IDL 定义（flatbuffers）转换为代码。

您可以使用 just codegen 生成代码。

文档链接

`.fbs` 文件可以包含文档字符串（`///`），这些文档字符串可以包含文档链接。它们应该写成如下形式：`[archetypes.Image]`。

目前仅支持对类型的链接。

链接检查不是由 codegen 执行的，但输出会隐式地由 `cargo doc`，`lychee` 等工具检查。

我们只支持默认的 rerun.scope 的 doclinks。

lib.rs:

此crate实现了Rerun的代码生成工具。

这些工具将语言无关的 IDL 定义（flatbuffers）转换为代码。

它们通过 pixi run codegen 被调用。

组织

代码生成过程分为4个阶段。

1. 从 flatbuffers 定义中生成二进制反射数据。

这仅仅是调用 flatbuffers 编译器（flatc）并使用正确的标志来生成二进制转储。

在代码中查找 compile_binary_schemas。

2. 运行语义遍历。

语义遍历将第一阶段生成的低级原始反射数据转换成更高级的对象，这些对象更容易检查/操作，并且整体上更容易使用。

在代码中查找 objects.rs。

3. 填充 Arrow 注册表。

Arrow 注册表跟踪所有类型定义并将它们映射到 Arrow 数据类型。

在代码中查找 arrow_registry.rs。

4. 为特定语言运行实际的代码生成遍历。

目前我们实现了两个不同的代码生成遍历：Python 和 Rust。

代码生成遍历使用第二阶段的语义对象和第三阶段的注册表来生成 Rerun SDK 的用户代码。

这些遍历故意采用了一种非常低技术含量的无额外功能的方法（拼接字符串，大量使用 unimplemented 等），以便在面对生成的代码中不断变化的需求时保持其灵活性。

在代码中查找 codegen/python.rs 和 codegen/rust.rs。

错误处理

请注意：这所有都是 构建时 代码，永远不会在运行时看到光明。因此，在这个包中没有必要进行复杂的错误处理：所有错误对构建来说都是致命的。

确保在出现问题后尽快崩溃，并使用 anyhow 的 with_context附加所有适当/可用的上下文（例如，始终包含有问题的类型/字段的完全限定名称），然后就可以出发了。

测试

与错误处理相同的评论：此代码在运行时变得无关紧要，因此对其进行测试几乎没有价值。

但是请确保测试其输出行为：re_types！

理解后缀的细微差别

所谓的 "后缀" 是应用于使用 Rerun IDL 定义的对象的效应，这些效应会影响这些对象的行为以及它们相互之间如何交互（所以，是的，单子。嘘！）。

在处理 Rerun 的 IDL 时，使用以下 3 种非常常见和明显不同的后缀：透明度、可空性和复数性。

广泛地说，我们可以这样描述这些后缀：

• 透明度允许绕过一个层级的类型（例如，从结构中 "提取" 一个字段）。
• 可空性指定数据在运行时是否可以未指定。
• 复数性指定数据是否实际上是同一类型的集合。

我们在这里说 "广泛" 是因为这些后缀最终对实际应用中的对象产生的影响将实际上取决于它们应用的对象类型，这些对象类型有 3 种：原型、组件和数据类型。

不仅如此，Rerun 的 IDL 中定义的对象会具体化为 3 个不同的环境：IDL 定义、Arrow 数据类型和本地代码（例如 Rust 和 Python）。

这些环境具有截然不同的特征、怪癖、陷阱和限制，这再次导致这些后缀在不同的环境中具有不同的、有时令人惊讶的行为，这也取决于我们感兴趣的环境。此外，请记住，Flatbuffers 和本地代码通常围绕结构数组的数组设计，而 Arrow 则是关于数组的结构！

总的来说，前缀、对象类型和环境之间的这些交互导致边缘情况组合爆炸，当涉及到（反）序列化代码甚至API设计时可能会非常混乱。

如有疑问，请查看 rerun.testing.archetypes.AffixFuzzer 的IDL定义、生成代码和测试套件以获取确切答案。