在开发应用程序的时候,常会需要在程序加入图片、声音等等的素材。以开发 Web 应用程序来说,还会需要用到很多 HTML 模板、CSS、JavaScript、语言档、数据库设置档等等的素材文件。这些素材文件常因为放不进程式可执行文件中,而只好另外放在文件系统的某个目录下,由程序在运行阶段的时候再去读取。像这样程序和素材分开存放的作法虽然很常见,但其实会引发许多问题。例如,在设置程序运行环境的时候,工序会变得复杂,系统管理员必须要按照程序的说明文档,将指定的素材放置到指定的路径之下。又或是把暴露在可执行文件之外的素材,交付给客户使用之后,难保他们不会将那些素材外流或是另作它用。讲难听一点就是有可能会被盗图、盗设计排版、盗 JS 程序、盗数据库,素材被他人盗用在其它的项目上。又或是一样的程序,只不过把外部素材改一改、换一换之后,就被他人当成是自己做的应用程序来卖了。

那么,Rust 编程语言要如何把外部文件素材给导入至程序内呢?

include_bytes

Rust 编程语言内置 include_bytes! 宏,可以传入一个文件路径,编译器在编译程序的时候就会去读取该文件,并将该文件内容直接转成 u8 数组,以 &'static [u8; N] 的类型回传。

fn main() {
    let file_data = include_bytes!("/path/to/file"); // &'static [u8; N]

    // do something ...
}

include_str

Rust 编程语言内置 include_str! 宏,类似 include_bytes! 宏,同样可以传入一个文件路径,编译器也会在编译程序的时候去读取该文件。不同的地方在于「include_str」宏会将文件以 UTF-8 编码成 Rust 编程语言的字符串,以 &'static str 的类型回传。

fn main() {
    let file_text = include_str!("/path/to/file"); // &'static str

    // do something ...
}

include_bytes! 和 include_str! 的相对路径

include_bytes! 和 include_str! 宏所输入的路径可以使用绝对路径或是相对路径。相对路径是相对于使用 include_bytes! 或 include_str! 宏的 .rs 源代码文件的路径,举例来说,如果源代码文件路径为 /path/to/file.rs,则 include_bytes!("123.jpg") 所使用到的文件为 /path/to/123.jpg;include_bytes!("../123.jpg") 所使用到的文件为 /path/123.jpg。

若是觉得路径相对于 .rs 源代码文件的路径在使用上会不太方便的话,也可以配合 concat! 和 env! 宏,将外部素材的路径指定到 Cargo 程序项目的根目录或根目录的子目录下。

fn main() {
    let file_data = include_bytes!(concat!(env!("CARGO_MANIFEST_DIR"), "/", "path/to/file"));

    // do something ...
}

如以上程序,就会去读取 Cargo 程序项目的根目录下的 path/to/file 这个文件。

include

Rust 编程语言另外还有内置一个 include! 宏,这个宏的使用方式跟 include_bytes! 和 include_str! 差不多,只不过它是直接把文件内容作为代码使用。如果您的外部素材是一个符合 Rust 编程语言语法的数组,或许可以使用这个 include! 宏。但是在大部分的情况下,应该要尽量少用它。

["Hello!", "Rust!"]
fn main() {
    let array = include!("/path/to/file_array");

    // do something ...
}

能解决编译时间增加的套件──Lazy Static Include

将外部素材与程序一同编译,除了会让编译出来的文件体积增大外,还会大大增加编译所需时间,使得开发效率下降。为了有效解决这个问题,笔者开发了一个「Lazy Static Include」套件,以 lazy_static_include_bytes!、lazy_static_include_str! 和 lazy_static_include_array! 宏来取代内置的 include_bytes!、include_str! 和 include!(用于数组时)宏。

顾名思义,这个套件利用 Lazy Load 的机制,在程序运行阶段使用到外部素材文件的时候,才会去读取文件。但是当我们使用 release 模式来编译 Cargo 程序项目的时候,这个套件就会把外部素材文件和 Rust 程序编译在一起。换句话说,就算我们正式发进程式的时候外部素材文件和 Rust 程序是编译在一起的,但是在开发阶段(非 release 模式时),由于是采用 Lazy Load 来读取文件,因此不会影响到编译时间,开发效率自然也就不会下降啦!

Crates.io

Cargo.toml

lazy-static-include = "*"

宏的使用

lazy_static_include_bytes! 和 lazy_static_include_str! 的用法差不多,以逗号分隔多个静态变量名称,并于每个静态变量后面使用 => 语法来传入要读取的文件路径,路径可以用字符串定数或是「元组(tuple)」来表示。每个静态变量名称前可以加上 pub 关键字来进行可见度的修饰,pub 关键字前可以加上文档注解或是其它属性。

例如:

use lazy_static_include::*;

lazy_static_include_str! {
    /// doc
    TEST => "data/test.txt",
}

lazy_static_include_str! {
    /// doc
    pub TEST2 => ("data", "test-2.txt"),
}

assert_eq!("This is just a test text.", TEST);
assert_eq!("Some text...", TEST2);

lazy_static_include_bytes! 和 lazy_static_include_str! 宏定义出来的静态变量,其类型是 lazy_static 的智能型指针,如果要获得 &'static [u8] 或是 &'static str 类型,可以使用 *(星号)进行「解参考」的动作。

use lazy_static_include::*;

lazy_static_include_bytes! {
    /// doc
    TEST => "data/test.txt",
}

let data: &'static [u8] = *TEST;
include_array

lazy_static_include_array 宏的话,其实也是跟 include 宏一样不太建议使用。第一个参数传入静态变量的名称和数组类型(以冒号 : 分隔),第二个参数传入要读取的文件路径,路径会相对于 Cargo 程序项目的根目录。如果静态变量是公开的(public),可以在静态变量名称前加上 pub 关键字。

例如:

[123, 456, 789, 1_000, 500000000000u64]
["Hi", "Hello", "哈啰"]
use lazy_static_include::*;

lazy_static_include_array! {
    /// doc
    TEST: [u64; 5] => "data/u64_array.txt",
}

lazy_static_include_array! {
    /// doc
    pub TEST2: [&'static str; 3] => ("data", "string_array.txt")
}

assert_eq!(123, TEST[0]);
assert_eq!(456, TEST[1]);
assert_eq!(789, TEST[2]);
assert_eq!(1000, TEST[3]);
assert_eq!(500000000000u64, TEST[4]);

assert_eq!("Hi", TEST2[0]);
assert_eq!("Hello", TEST2[1]);
assert_eq!("哈啰", TEST2[2]);