资产管理和构建管道

相关源文件

• .gitmodules
• assets/acknowledgements.bin
• assets/create.sh
• assets/syntaxes.bin
• assets/themes.bin
• examples/advanced.rs
• examples/list_syntaxes_and_themes.rs
• src/assets/build_assets.rs
• src/assets/build_assets/acknowledgements.rs
• src/assets/lazy_theme_set.rs
• src/assets/serialized_syntax_set.rs
• tests/assets.rs

bat 的资产管理与构建管道负责打包、构建和加载对 bat 核心功能至关重要的语法高亮定义和主题。该系统管理超过 150 个外部存储库作为 Git 子模块，将它们编译成优化的二进制资产，并通过延迟评估技术实现高效的运行时加载。

有关如何将语法高亮应用于内容的详细信息，请参阅 语法高亮。

概述

bat 的资产管理系统解决了几个关键需求：

• 将大量的语法定义和主题与应用程序一起打包
• 允许在运行时高效地仅加载所需的资产
• 通过自定义语法和主题添加来支持用户自定义
• 尽管资产数量庞大，仍能保持可管理的二进制文件大小

该系统使用 Git 子模块来跟踪外部语法和主题存储库，通过构建过程将它们编译成二进制资产，并使用运行时加载机制，优先加载可用的自定义资产。

来源：.gitmodules1-275 src/assets/build_assets.rs12-36

资产来源

将语法定义和主题作为子模块

bat 将其语法定义和主题作为 Git 子模块进行管理，这允许跟踪外部存储库的特定版本。

存储库包括：

1. Sublime Text 包 - 语法定义的主要来源，由 Sublime HQ 维护
2. 额外语言支持 - 来自社区的额外语法定义
3. 主题集合 - 用于语法高亮的各种颜色方案

.gitmodules 文件定义了 100 多个子模块，组织结构如下：

• assets/syntaxes/01_Packages - 来自 Sublime Text 的核心语法定义
• assets/syntaxes/02_Extra/[Language] - 额外的语言支持
• assets/themes/[Theme] - 各种主题存储库

来源：.gitmodules1-275

自定义资产目录

除了内置资产外，bat 还支持用户在自定义目录中定义资产，通常位于 ~/.config/bat/syntaxes/ 和 ~/.config/bat/themes/。这些自定义资产会覆盖同名的内置资产。

来源：src/assets/build_assets.rs38-63 src/assets/build_assets.rs65-89

资产构建过程

资产构建过程将原始的语法和主题文件转换为优化的二进制格式，以便在运行时高效加载。

构建过程

1. 初始化阶段:

   • create.sh 脚本确保所有子模块都已初始化。
   • 应用补丁以修复某些语法定义中的问题
   • 调用 bat cache --build 来编译资产

2. 主题处理:

   • build_theme_set() 从主题目录加载主题定义
   • 如果指定，则集成任何内置主题
   • 转换为 LazyThemeSet 以实现高效加载

3. 语法处理:

   • build_syntax_set_builder() 从语法定义创建语法集
   • 添加内置和目录语法
   • 检查是否存在未链接的上下文（语法定义问题）

4. 致谢生成:

   • 扫描 LICENSE 和 NOTICE 文件
   • 将它们编译成单个文档
   • 用于遵守捆绑资产的许可要求

5. 资产序列化:

   • 使用 bincode 序列化主题集、语法集和致谢信息
   • 可选使用 flate2 (zlib) 进行压缩
   • 写入目标目录中的二进制文件

构建过程会生成三个主要的二进制文件：

• syntaxes.bin：包含序列化的语法定义
• themes.bin：包含序列化的主题
• acknowledgements.bin：包含许可信息

它还会创建一个元数据文件来跟踪已构建资产的版本。

来源：assets/create.sh1-70 src/assets/build_assets.rs12-139 src/assets/build_assets/acknowledgements.rs18-45

运行时资产加载

在运行时，bat 采用复杂的资产加载系统，在性能和内存使用之间取得平衡。

资产来源选择

bat 使用优先排序的方法来确定加载哪些资产：

1. 检查用户目录中的自定义资产
2. 回退到包含在二进制文件中的嵌入式资产

延迟加载机制

为了优化内存使用和启动时间，bat 使用两种不同的加载方法：

1. LazyThemeSet：主题在被请求时按需加载

   • 将主题以序列化形式存储
   • 仅在需要时反序列化单个主题
   • 使用 OnceCell 确保主题最多只反序列化一次

2. SerializedSyntaxSet：语法定义作为完整集进行加载

   • 可以从文件或嵌入的二进制文件中加载
   • 在需要时作为整体反序列化

这种方法意味着不常用的主题在被请求之前不会占用内存，而语法定义（通常是必需的）则作为完整集加载以获得最佳性能。

来源：src/assets/lazy_theme_set.rs1-104 src/assets/serialized_syntax_set.rs1-28

自定义资产管理

bat 提供了一个机制，允许用户通过 bat cache 命令添加自己的语法定义和主题。

添加自定义资产

用户可以通过以下方式添加自定义资产：

1. 创建相应的目录

   • ~/.config/bat/syntaxes/ 用于语法定义
   • ~/.config/bat/themes/ 用于主题

2. 添加相应的文件

   • .sublime-syntax 文件用于语法定义
   • .tmTheme 文件用于主题

3. 运行 bat cache --build 来编译资产

自定义资产会覆盖同名的内置资产，允许用户覆盖或扩展默认行为。

缓存管理

bat cache 命令提供了多种操作：

• --build：从所有可用来源构建缓存
• --clear：移除任何现有的缓存
• --source：指定自定义资产来源目录
• --target：指定缓存的自定义目标目录
• --blank：从空白缓存开始，忽略内置定义

这种灵活的方法允许用户完全自定义 bat 中的高亮体验。

来源：assets/create.sh42-69 src/assets/build_assets.rs101-139 tests/assets.rs1-42 examples/advanced.rs1-18 examples/list_syntaxes_and_themes.rs1-19

测试与验证

资产管理系统包含测试，以确保所有预期的主题都存在，并且序列化/反序列化过程能够正常工作。

这些测试有助于在添加新资产或更新现有资产时维护兼容性。

来源：tests/assets.rs1-42