Iftree: 包含文件树 🌳

将许多文件包含在您的 Rust 代码中，以创建自包含的二进制文件。

亮点:

• 使用 路径模式 包含或排除文件。
• 编译时检查的文件查找在运行时 快速（常数时间）。
• 可定制：将任何数据与文件关联。
• 许多 示例，包括 食谱。

另请参阅 相关项目。

动机

自包含的二进制文件易于分发，因为它们包含所需的任何文件数据，例如游戏资源、Web 模板等。

标准库的 std::include_str! 包含了给定文件的全部内容。Iftree 以两种方式泛化这一点

• 不仅是一个，而是可以一次包含多个文件，使用类似于 .gitignore 的格式中的 路径模式。模式灵活：您可以将多个文件夹包含在内，跳过隐藏文件，按文件扩展名过滤，选择固定文件列表等。
• 除了包含文件内容之外，文件还可以与 任何数据 字段相关联，例如额外的文件元数据。

概念上

std:       include_str!("my_file")
Iftree:    any_macro!("my_files/**")

用法

既然您已经了解了原因和内容，那么了解如何使用。以下快速入门展示了基本用法。

快速入门

// Say you have these files:
//
//     my_assets/
//     ├── file_a
//     ├── file_b
//     └── folder/
//         └── file_c

// Include data from this file tree in your code like so:
#[iftree::include_file_tree("paths = '/my_assets/**'")]
pub struct MyAsset {
    relative_path: &'static str,
    contents_str: &'static str,
}

fn main() {
    // Based on this, an array `ASSETS` of `MyAsset` instances is generated:
    assert_eq!(ASSETS.len(), 3);
    assert_eq!(ASSETS[0].relative_path, "my_assets/file_a");
    assert_eq!(ASSETS[0].contents_str, "… contents file_a\n");
    assert_eq!(ASSETS[1].contents_str, "… contents file_b\n");
    assert_eq!(ASSETS[2].contents_str, "… file_c\n");

    // Also, variables `base::x::y::MY_FILE` are generated (named by file path):
    assert_eq!(base::my_assets::FILE_A.relative_path, "my_assets/file_a");
    assert_eq!(base::my_assets::FILE_A.contents_str, "… contents file_a\n");
    assert_eq!(base::my_assets::FILE_B.contents_str, "… contents file_b\n");
    assert_eq!(base::my_assets::folder::FILE_C.contents_str, "… file_c\n");
}

详细指南

1. 将 依赖 iftree = "1.0" 添加到您的清单（Cargo.toml）。

2. 定义您的 资产类型，它只是自定义 struct 或类型别名。例如

   pub struct MyAsset;
   

3. 接下来，通过注解您的资产类型来 过滤 要包含的文件。例如

   #[iftree::include_file_tree("paths = '/my_assets/**'")]
   pub struct MyAsset;
   

   宏参数是一个TOML字符串字面量。这里的paths选项支持类似于.gitignore的路径模式，每行一个模式。这些路径默认相对于包含你的清单的文件夹。有关更多信息，请参阅paths配置。

4. 定义你的资产类型的数据字段。示例

   #[iftree::include_file_tree("paths = '/my_assets/**'")]
   pub struct MyAsset {
       relative_path: &'static str,
       contents_bytes: &'static [u8],
   }
   

   在构建你的项目时，将针对每个文件实例化资产类型一次。

   默认情况下，如果存在，字段relative_path将填充文件路径，字段contents_bytes将填充原始文件内容，并且通过名称识别一些其他标准字段。

   但是，你可以自定义以包含任意文件数据。

5. 现在你可以通过生成的ASSETS数组访问你的文件数据。示例

   assert_eq!(ASSETS[0].relative_path, "my_assets/my_file");
   assert_eq!(ASSETS[0].contents_bytes, b"file contents");
   

   此外，对于每个文件x/y/my_file，将生成一个变量base::x::y::MY_FILE（除非通过template.identifiers配置禁用）。这样的变量是对相应的ASSETS数组元素的引用。示例

   assert_eq!(base::my_assets::MY_FILE.relative_path, "my_assets/my_file");
   assert_eq!(base::my_assets::MY_FILE.contents_bytes, b"file contents");
   

如果您想通过示例进行探索，有一个examples文件夹。文档链接到有用的单个示例。

您可以从基本示例开始。对于更复杂的情况，请参阅展示示例。

请注意，一些示例需要从清单的dev-dependencies中获取额外的依赖项。

标准字段

当你只使用以下字段的子集时，将生成你的资产类型的初始化器而无需进一步配置。请参阅示例。

• contents_bytes: &'static [u8]

  将文件内容作为字节数组，使用std::include_bytes。

• contents_str: &'static str

  将文件内容解释为UTF-8字符串，使用std::include_str。

• get_bytes: fn() -> std::borrow::Cow<'static, [u8]>

  在调试构建中（即，当debug_assertions被启用时），此函数每次在运行时都会重新读取文件。如果发生任何错误（例如，文件不存在），则会引发恐慌。这有助于加快开发速度，因为它可以避免仅更改资产文件内容时的重建（注意，如果添加、重命名或删除资产，您仍然需要重新构建）。

  在发布构建中，它返回编译时包含的文件内容，使用std::include_bytes。

• get_str: fn() -> std::borrow::Cow<'static, str>

  与get_bytes相同，但用于将文件内容解释为UTF-8字符串，使用std::include_str。

• relative_path: &'static str

  相对于基本文件夹的文件路径，默认情况下是包含您的清单（Cargo.toml）的文件夹。路径组件由一个斜杠/分隔，独立于您的平台。

macro_rules! my_initialize {
    ($relative_path:literal, $absolute_path:literal) => {
        MyAsset {
            path: $relative_path,
            size_in_bytes: include_bytes!($absolute_path).len(),
        }
    };
}

#[iftree::include_file_tree(
    "
paths = '/my_assets/**'
template.initializer = 'my_initialize'
"
)]
pub struct MyAsset {
    path: &'static str,
    size_in_bytes: usize,
}

fn main() {
    assert_eq!(base::my_assets::FILE_A.path, "my_assets/file_a");
    assert_eq!(base::my_assets::FILE_A.size_in_bytes, 20);
    assert_eq!(base::my_assets::FILE_B.path, "my_assets/file_b");
}

[[template]]
visit_base = 'visit_my_base'
visit_folder = 'visit_my_folder'
visit_file = 'visit_my_file'