staticfilemap

Procedural macro to embed optionally compressed files during compilation.

Similar to include_file! or include_dir!, but accepts a list of files that can be specified through environment variables and supports compression with LZ4 or zstd.

Usage

Derive from StaticFileMap to create a map.

Specify the files to be included and the names they should be accessed by with the files and names attributes. These can either be strings containing values separated with ;, or environment variables containing them when the parse attribute is set to env. Relative paths are resolved relative to CARGO_MANIFEST_DIR. If the names attribute is not specified, the names are inferred from the filenames.

The compression level is controlled by the compression attribute. With a compression level above 0 the included files are compresed with Zstd. Zstd supports a compression level up to 21. Alternatively, LZ4 can be used for compression by setting the algorithm attribute to lz4. LZ4 accepts a compression level up to 12.

The cargo features zstd and lz4 are available to select compression support. zstd is enabled by default.

Files can be accessed as &'static [u8] slices by the get(name) and get_match(name) functions at runtime. get_match(name) accepts partial names if only one name matches. keys() returns a list of all keys.

See the examples, the tests or the implementation for details.

Dependency

[dependencies]
staticfilemap = "^0.5"

Examples

use staticfilemap::StaticFileMap;

#[derive(StaticFileMap)]
#[names = "a;b"]
#[files = "README.md;LICENSE"]
struct StaticMap;

fn main() {
    let content: &[u8] = StaticMap::get("b").unwrap();
    let keys: &[&str] = StaticMap::keys();
}

use staticfilemap::StaticFileMap;
use minilz4::Decode;
use std::io::Read;

#[derive(StaticFileMap)]
#[parse = "env"]
#[names = "FILENAMES"]
#[files = "FILEPATHS"]
#[compression = 8]
#[algorithm = "lz4"]
struct StaticMap;

fn main() {
    let compressed = StaticMap::get_match("diogenes")
        .expect("file matching diogenes was not included");
    let content = compressed.decode();
}

use staticfilemap::StaticFileMap;
use zstd::decode_all;

#[derive(StaticFileMap)]
#[parse = "env"]
#[names = "FILENAMES"]
#[files = "FILEPATHS"]
#[compression = 8]
struct StaticMap;

fn main() {
    let mut compressed = StaticMap::get("diogenes.txt")
        .expect("file diogenes.txt was not included");
    let content = decode_all(&mut compressed);
}

use staticfilemap::StaticFileMap;

#[derive(StaticFileMap)]
#[files = "README.md;LICENSE"]
struct StaticMap;

fn main() {
    for (key, data) in StaticMap::iter() {
        println!("{}: {}", key, String::from_utf8_lossy(data));
    }
}