Skip to content
BranchesTags

Repository files navigation

embed_it

Build Statuscrates.ioCoverage

Include any directory as a struct, and the entire tree will be generated as Rust structures and traits

Imagine a project structure like this:

  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml

You can use a macro to expand it into Rust code:

#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}

Known issues

Long compilation time with many files

If your directory contains a very large number of files, the compile time can increase significantly.

Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.

macro invocation exceeds token limit error in rust-analyzer

When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.

Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.

Intellisense issues in RustRover

In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.

Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.

Fields

embed

The main attribute

fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")

DirAttr

fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section

FileAttr

fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section

EmbeddedTraits list

nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits

EntryAttr

fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry

FieldAttr

You can add any additional fields, which will be created in runtime (but only once) from a dir or a file. For each field defined in macros a special trait will be generated inside the module containing a root structure.

fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}

Include / Exclude

You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir. Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.

#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}

Hash traits

You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.

DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]

The example below compiles only if all hash features listed in the table above are enabled.

#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}

Compression traits

You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.

It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.

The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.

DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}

More complex example

#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}

How does fs-entry's name turn into Rust identifiers?

Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.

  • one+txt
  • one-txt
  • one_txt

The macro handles this problem and generates methods with a numeric suffix. In that case it would be

  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()

Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.

This works for struct names in the same way

  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2

What code will be generated by macros

  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:
    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child

NOTE: All instances are static, and this staticness is achieved

  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}

About

Include your assets statically into your application with a strict structure

Resources

Readme
MIT license
Activity

Stars

94 stars

Watchers

2 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
GitHub - riberk/embed_it: Include your assets statically into your application with a strict structure · GitHub
Skip to content
BranchesTags
Repository files navigation
embed_it
Build Statuscrates.ioCoverage
Include any directory as a struct, and the entire tree will be generated as Rust structures and traits
Imagine a project structure like this:
  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml
You can use a macro to expand it into Rust code:
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}
Known issues
Long compilation time with many files
If your directory contains a very large number of files, the compile time can increase significantly.
Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.
macro invocation exceeds token limit error in rust-analyzer
When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.
Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.
Intellisense issues in RustRover
In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.
Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.
Fields
embed
The main attribute
fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")
 DirAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 FileAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 EmbeddedTraits list
nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits
 EntryAttr
fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry
 FieldAttr
You can add any additional fields, which will be created in runtime (but only once) from a dir or a file.
For each field defined in macros a special trait will be generated inside the module containing a root structure.
fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}
 Include / Exclude
You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir.
Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}
 Hash traits
You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.
DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]
The example below compiles only if all hash features listed in the table above are enabled.
#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}
 Compression traits
You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.
It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.
The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.
DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}
More complex example
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}
How does fs-entry's name turn into Rust identifiers?
Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.
  • one+txt
  • one-txt
  • one_txt
The macro handles this problem and generates methods with a numeric suffix. In that case it would be
  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()
Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.
This works for struct names in the same way
  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2
What code will be generated by macros
  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:

    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child
NOTE: All instances are static, and this staticness is achieved
  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}
About
Include your assets statically into your application with a strict structure
Resources
Readme
MIT license
Activity
Stars
94 stars
Watchers
2 watching
Forks
3 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - riberk/embed_it: Include your assets statically into your application with a strict structure · GitHub
Skip to content
BranchesTags
Repository files navigation
embed_it
Build Statuscrates.ioCoverage
Include any directory as a struct, and the entire tree will be generated as Rust structures and traits
Imagine a project structure like this:
  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml
You can use a macro to expand it into Rust code:
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}
Known issues
Long compilation time with many files
If your directory contains a very large number of files, the compile time can increase significantly.
Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.
macro invocation exceeds token limit error in rust-analyzer
When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.
Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.
Intellisense issues in RustRover
In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.
Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.
Fields
embed
The main attribute
fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")
 DirAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 FileAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 EmbeddedTraits list
nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits
 EntryAttr
fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry
 FieldAttr
You can add any additional fields, which will be created in runtime (but only once) from a dir or a file.
For each field defined in macros a special trait will be generated inside the module containing a root structure.
fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}
 Include / Exclude
You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir.
Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}
 Hash traits
You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.
DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]
The example below compiles only if all hash features listed in the table above are enabled.
#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}
 Compression traits
You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.
It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.
The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.
DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}
More complex example
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}
How does fs-entry's name turn into Rust identifiers?
Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.
  • one+txt
  • one-txt
  • one_txt
The macro handles this problem and generates methods with a numeric suffix. In that case it would be
  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()
Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.
This works for struct names in the same way
  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2
What code will be generated by macros
  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:

    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child
NOTE: All instances are static, and this staticness is achieved
  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}
About
Include your assets statically into your application with a strict structure
Resources
Readme
MIT license
Activity
Stars
94 stars
Watchers
2 watching
Forks
3 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - riberk/embed_it: Include your assets statically into your application with a strict structure · GitHub
Skip to content
BranchesTags
Repository files navigation
embed_it
Build Statuscrates.ioCoverage
Include any directory as a struct, and the entire tree will be generated as Rust structures and traits
Imagine a project structure like this:
  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml
You can use a macro to expand it into Rust code:
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}
Known issues
Long compilation time with many files
If your directory contains a very large number of files, the compile time can increase significantly.
Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.
macro invocation exceeds token limit error in rust-analyzer
When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.
Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.
Intellisense issues in RustRover
In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.
Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.
Fields
embed
The main attribute
fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")
 DirAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 FileAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 EmbeddedTraits list
nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits
 EntryAttr
fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry
 FieldAttr
You can add any additional fields, which will be created in runtime (but only once) from a dir or a file.
For each field defined in macros a special trait will be generated inside the module containing a root structure.
fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}
 Include / Exclude
You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir.
Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}
 Hash traits
You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.
DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]
The example below compiles only if all hash features listed in the table above are enabled.
#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}
 Compression traits
You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.
It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.
The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.
DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}
More complex example
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}
How does fs-entry's name turn into Rust identifiers?
Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.
  • one+txt
  • one-txt
  • one_txt
The macro handles this problem and generates methods with a numeric suffix. In that case it would be
  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()
Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.
This works for struct names in the same way
  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2
What code will be generated by macros
  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:

    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child
NOTE: All instances are static, and this staticness is achieved
  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}
About
Include your assets statically into your application with a strict structure
Resources
Readme
MIT license
Activity
Stars
94 stars
Watchers
2 watching
Forks
3 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
GitHub - riberk/embed_it: Include your assets statically into your application with a strict structure · GitHub
Skip to content
BranchesTags
Repository files navigation
embed_it
Build Statuscrates.ioCoverage
Include any directory as a struct, and the entire tree will be generated as Rust structures and traits
Imagine a project structure like this:
  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml
You can use a macro to expand it into Rust code:
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}
Known issues
Long compilation time with many files
If your directory contains a very large number of files, the compile time can increase significantly.
Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.
macro invocation exceeds token limit error in rust-analyzer
When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.
Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.
Intellisense issues in RustRover
In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.
Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.
Fields
embed
The main attribute
fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")
 DirAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 FileAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 EmbeddedTraits list
nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits
 EntryAttr
fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry
 FieldAttr
You can add any additional fields, which will be created in runtime (but only once) from a dir or a file.
For each field defined in macros a special trait will be generated inside the module containing a root structure.
fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}
 Include / Exclude
You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir.
Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}
 Hash traits
You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.
DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]
The example below compiles only if all hash features listed in the table above are enabled.
#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}
 Compression traits
You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.
It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.
The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.
DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}
More complex example
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}
How does fs-entry's name turn into Rust identifiers?
Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.
  • one+txt
  • one-txt
  • one_txt
The macro handles this problem and generates methods with a numeric suffix. In that case it would be
  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()
Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.
This works for struct names in the same way
  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2
What code will be generated by macros
  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:

    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child
NOTE: All instances are static, and this staticness is achieved
  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}
About
Include your assets statically into your application with a strict structure
Resources
Readme
MIT license
Activity
Stars
94 stars
Watchers
2 watching
Forks
3 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - riberk/embed_it: Include your assets statically into your application with a strict structure · GitHub
Skip to content
BranchesTags
Repository files navigation
embed_it
Build Statuscrates.ioCoverage
Include any directory as a struct, and the entire tree will be generated as Rust structures and traits
Imagine a project structure like this:
  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml
You can use a macro to expand it into Rust code:
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}
Known issues
Long compilation time with many files
If your directory contains a very large number of files, the compile time can increase significantly.
Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.
macro invocation exceeds token limit error in rust-analyzer
When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.
Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.
Intellisense issues in RustRover
In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.
Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.
Fields
embed
The main attribute
fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")
 DirAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 FileAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 EmbeddedTraits list
nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits
 EntryAttr
fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry
 FieldAttr
You can add any additional fields, which will be created in runtime (but only once) from a dir or a file.
For each field defined in macros a special trait will be generated inside the module containing a root structure.
fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}
 Include / Exclude
You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir.
Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}
 Hash traits
You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.
DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]
The example below compiles only if all hash features listed in the table above are enabled.
#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}
 Compression traits
You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.
It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.
The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.
DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}
More complex example
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}
How does fs-entry's name turn into Rust identifiers?
Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.
  • one+txt
  • one-txt
  • one_txt
The macro handles this problem and generates methods with a numeric suffix. In that case it would be
  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()
Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.
This works for struct names in the same way
  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2
What code will be generated by macros
  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:

    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child
NOTE: All instances are static, and this staticness is achieved
  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}
About
Include your assets statically into your application with a strict structure
Resources
Readme
MIT license
Activity
Stars
94 stars
Watchers
2 watching
Forks
3 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - riberk/embed_it: Include your assets statically into your application with a strict structure · GitHub
Skip to content
BranchesTags
Repository files navigation
embed_it
Build Statuscrates.ioCoverage
Include any directory as a struct, and the entire tree will be generated as Rust structures and traits
Imagine a project structure like this:
  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml
You can use a macro to expand it into Rust code:
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}
Known issues
Long compilation time with many files
If your directory contains a very large number of files, the compile time can increase significantly.
Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.
macro invocation exceeds token limit error in rust-analyzer
When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.
Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.
Intellisense issues in RustRover
In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.
Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.
Fields
embed
The main attribute
fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")
 DirAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 FileAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 EmbeddedTraits list
nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits
 EntryAttr
fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry
 FieldAttr
You can add any additional fields, which will be created in runtime (but only once) from a dir or a file.
For each field defined in macros a special trait will be generated inside the module containing a root structure.
fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}
 Include / Exclude
You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir.
Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}
 Hash traits
You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.
DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]
The example below compiles only if all hash features listed in the table above are enabled.
#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}
 Compression traits
You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.
It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.
The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.
DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}
More complex example
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}
How does fs-entry's name turn into Rust identifiers?
Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.
  • one+txt
  • one-txt
  • one_txt
The macro handles this problem and generates methods with a numeric suffix. In that case it would be
  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()
Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.
This works for struct names in the same way
  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2
What code will be generated by macros
  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:

    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child
NOTE: All instances are static, and this staticness is achieved
  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}
About
Include your assets statically into your application with a strict structure
Resources
Readme
MIT license
Activity
Stars
94 stars
Watchers
2 watching
Forks
3 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
GitHub - riberk/embed_it: Include your assets statically into your application with a strict structure · GitHub
Skip to content
BranchesTags
Repository files navigation
embed_it
Build Statuscrates.ioCoverage
Include any directory as a struct, and the entire tree will be generated as Rust structures and traits
Imagine a project structure like this:
  • assets/
    • one_txt/
      • hello
      • world
    • hello.txt
    • one.txt
    • world.txt
  • src
  • Cargo.toml
You can use a macro to expand it into Rust code:
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", support_alt_separator,)]pubstructAssets;fnmain(){use embed_it::EmbeddedPath;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.hello().path(),&EmbeddedPath::new("hello.txt","hello.txt","hello"));assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.one().path(),&EmbeddedPath::new("one.txt","one.txt","one"));assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.world().path(),&EmbeddedPath::new("world.txt","world.txt","world"));assert_eq!(Assets.one_txt().path(),&EmbeddedPath::new("one_txt","one_txt","one_txt"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().hello().path(),&EmbeddedPath::new("one_txt/hello","hello","hello"));assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().world().path(),&EmbeddedPath::new("one_txt/world","world","world"));// or with dynamic dispatchassert_eq!(Assets.get("one_txt/hello").unwrap().file().unwrap().content(),b"hello");// We can use Windows-style paths due to the `support_alt_separator` attributeassert_eq!(Assets.get("one_txt\\hello").unwrap().file().unwrap().content(),b"hello");}
Known issues
Long compilation time with many files
If your directory contains a very large number of files, the compile time can increase significantly.
Possible solution: Move those assets into a separate crate. This way, the main build won’t be slowed down by the large amount of embedded content, and changes in the asset crate won’t force a full rebuild of your main project.
macro invocation exceeds token limit error in rust-analyzer
When there are thousands of files/directories (around 5000 or more), rust-analyzer can fail with the error that the macro exceeds the token limit. This is due to a hard-coded limit in rust-analyzer that is not currently configurable tracking issue.
Possible workaround: Split the assets into multiple directories and generate several smaller embedded structures, each containing fewer files, to reduce the total token count.
Intellisense issues in RustRover
In JetBrains RustRover, intellisense might stop working when the number of files/directories reaches a similar high threshold. The exact cause and any permanent solution are currently unclear.
Possible workaround: As above, splitting assets into multiple directories with separate macro invocations may help avoid hitting internal limits.
Fields
embed
The main attribute
fieldtypemultiplerequireddefaultdescription
pathStringfalsetrue-The path to the directory with assets. It may contain compile-time environment variables (or user defined) in format $CARGO_MANIFEST_DIR or ${CARGO_MANIFEST_DIR}
dirDirAttrfalsefalseDirAttr::default()Changes the setting for how the Dirtrait and its implementations are generated. See more in the Dir Attr section
fileFileAttrfalsefalseFileAttr::default()Changes the setting for how the File trait and its implementations are generated. See more in the File Attr section
entryEntryAttrfalsefalseEntryAttr::default()Changes the setting for how the Entry struct and its implementations are generated. See more in the Entry Attr section
with_extensionboolfalsefalsefalseUse file extensions for method and struct names
support_alt_separatorboolfalsefalsefalseIf true, getting a value from the directory's Index replaces \ with /. In other words, you can use Windows-style paths with the get method, for example, Assets.get("a\\b\\c.txt")
 DirAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseDirSpecifies the trait name that will be used for a directory
field_factory_trait_nameIdentfalsefalseDirFieldFactorySpecifies the trait name that will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Entries, Index, Meta, Debug
DirectChildCount, RecursiveChildCount		What traits will be derived for every directory and what bounds will be set for the Dir trait. See also EmbeddedTraits list and Hash traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a directory. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 FileAttr
fieldtypemultiplerequireddefaultdescription
derive_default_traitsboolfalsefalsetrueDetermines whether default traits will be derived (see the derive row in the table)
trait_nameIdentfalsefalseFileWhat trait name will be used for a directory
field_factory_trait_nameIdentfalsefalseFileFieldFactoryWhat trait name will be used for a directory field factory
deriveVec<DirTrait>truefalsePath, Meta, Debug, ContentWhat traits will be derived for every directory and what bounds will be set for a Dir trait. See also EmbeddedTraits list, Hash traits, Compression traits
fieldVec<FieldAttr>truefalsevec![]Adds additional fields for a file. See more in the Field Attr section
includePathMatchSettruefalsePathMatchSet::AnySee more in the Include / Exclude section
excludePathMatchSettruefalsePathMatchSet::NoneSee more in the Include / Exclude section
 EmbeddedTraits list
nametraitdir or filemethodpurpose
Path[crate::EntryPath]anyfn path(&self) -> &'static EmbeddedPath;Provides full information about a path of an entry
Entries<auto generated>dirfn entries(&self) -> &'static [Entry]Provides direct children of a dir
Index<auto generated>dirfn get(&self, path: &str) -> Option<&'static Entry>Provides fast access (HashMap) to all children (recursively). It constructs hash set on every level dir and might use some memory if there are a lot of entries
DirectChildCount[crate::DirectChildCount]dirfn direct_child_count(&self) -> usize;Provides the number of direct children
RecursiveChildCount[crate::RecursiveChildCount]dirfn recursive_child_count(&self) -> usize;Provides the total number of children, including nested subdirectories
Meta[crate::Meta]anyfn metadata(&self) -> &'static Metadata;Provides metadata of an entry
Debug[std::fmt::Debug]anyDebugs structs
Content[crate::Content]filefn content(&self) -> &'static [u8];Provides content of a file
StrContent[crate::StrContent]filefn str_content(&self) -> &'static str;Provides content of a file as a str
Hashes<various>anyfn <name>[<_bits>](&self) -> &'static [u8; <bits>];Provides hash of a file content or a directory structure with files' hashes. See also Hash traits
Compression<various>filefn <name>_content(&self) -> &'static [u8];Provides the compressed content of a file. See also Compression traits
 EntryAttr
fieldtypemultiplerequireddefaultdescription
struct_nameIdentfalsefalseEntryWhat struct name will be used for an entry
 FieldAttr
You can add any additional fields, which will be created in runtime (but only once) from a dir or a file.
For each field defined in macros a special trait will be generated inside the module containing a root structure.
fieldtypemultiplerequireddefaultdescription
nameIdentfalsetrueThe name of the method that will be used by the trait
factorysyn::PathfalsetrueThe path to a factory, that will be used to create an instance of the field and to determine a field type
trait_nameOption<Ident>falsefalse{name.to_pascal_case()}FieldThe name of the field trait
regexOption<String>falsefalseNoneRegular expression to match a fs entry path. The trait is implemented for a struct only if the regex matches
patternOption<String>falsefalseNoneGlob pattern to match a fs entry path. The trait is implemented for a struct only if the pattern matches
globalboolfalsefalsefalseIf true, the trait will be implemented for the dynamic dispatch struct and you can use it with Index and Entries
use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( field(// it is a trait method name used to get an instance of a field.// you can use your own name for the trait with attribute `trait_name`.// By default it is `{name.to_pascal()}Field`.// In that case it will be `AsStrField`. name = "as_str",// factory is a path to the struct implementing either// a trait self::FileFieldFactory for target = "file"// or a trait self::DirFieldFactory for target = "dir" factory = AsStr,// glob pattern pattern = "*.txt",),), dir( field( name = "children", factory = crate::Children, regex = ".+_txt",), field( name = global_children, factory = crate::Children,// the trait will be bound of the main trait global,), field( name = "root_children", trait_name = "Root", factory = crate::Children,// this trait will be implemented only for root struct (`Assets`) regex = ""),),)]pubstructAssets;pubstructAsStr(&'staticstr);implFileFieldFactoryforAsStr{typeField = Option<Self>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{from_utf8(data.content()).map(AsStr).ok()}}pubstructChildren;implDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:Dir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|e| e.map(|d| d.path(), |f| f.path()).value().name()).collect()}}fnmain(){// the field `as_str`useAsStrField;assert_eq!(Assets.hello().content(),b"hello");assert_eq!(Assets.one().content(),b"one");assert_eq!(Assets.world().content(),b"world");assert_eq!(Assets.hello().as_str().as_ref().unwrap().0,"hello");assert_eq!(Assets.one().as_str().as_ref().unwrap().0,"one");assert_eq!(Assets.world().as_str().as_ref().unwrap().0,"world");// this is not compile due to `pattern` (`one_txt/hello` has no extension)// Assets.one_txt().as_str()// the field `children`useChildrenField;assert_eq!(Assets.one_txt().children(),&vec!["hello","world"]);// the field `root_children`useRoot;assert_eq!(Assets.root_children(),&vec!["one_txt","hello.txt","one.txt","world.txt"]);// the field `global_children`useGlobalChildrenField;// we can use it with dynamic dispatchassert_eq!(Assets.get("one_txt").unwrap().dir().unwrap().global_children(),&vec!["hello","world"]);}
 Include / Exclude
You can control which files / directories will be included into a struct with multiple include(pattern = "*.txt", regex = ".*\\.txt$") and exclude(pattern = "*.txt", regex = ".*\\.txt$") attributes on file and dir.
Matching is done on relative file paths, via either a glob pattern, a regular expression or both. exclude attributes have higher priority than include attributes.
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive_default_traits = false, exclude(pattern = "*_txt"), derive(Path), derive(Index),), file( derive_default_traits = false, include(regex = ".*e.*"), derive(Path),))]pubstructAssets;fnmain(){assert!(Assets.get("one.txt").is_some());assert!(Assets.get("hello.txt").is_some());assert!(Assets.get("world.txt").is_none());assert!(Assets.get("one_txt").is_none());}
 Hash traits
You can use any combination of hash traits on dir and file. For a file, it hashes its content; for a directory, it hashes every entry name and entry hash if applicable (order — directories first, then files, and finally by path). The hash is stored as a constant array of bytes.
DeriveRequired featureTrait
Md5md5[crate::Md5Hash]
Sha1sha1[crate::Sha1Hash]
Sha2_224sha2[crate::Sha2_224Hash]
Sha2_256sha2[crate::Sha2_256Hash]
Sha2_384sha2[crate::Sha2_384Hash]
Sha2_512sha2[crate::Sha2_512Hash]
Sha3_224sha3[crate::Sha3_224Hash]
Sha3_256sha3[crate::Sha3_256Hash]
Sha3_384sha3[crate::Sha3_384Hash]
Sha3_512sha3[crate::Sha3_512Hash]
Blake3blake3[crate::Blake3_256Hash]
The example below compiles only if all hash features listed in the table above are enabled.
#[cfg( all( feature = "md5", feature = "sha1", feature = "sha2", feature = "sha3", feature = "blake3"))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),), file( derive(Md5), derive(Sha1), derive(Sha2_224), derive(Sha2_256), derive(Sha2_384), derive(Sha2_512), derive(Sha3_224), derive(Sha3_256), derive(Sha3_384), derive(Sha3_512), derive(Blake3),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.md5(),&hex!("56e71a41c76b1544c52477adf4c8e2f7"));assert_eq!(Assets.sha1(),&hex!("26da80338f55108be5bcce49285a4154f6705599"));assert_eq!(Assets.sha2_224(),&hex!("360c16e2d8135a337cc6ddf4134ec9cc69dd65b779db2a2807f941e4"));assert_eq!(Assets.sha2_256(),&hex!("e16b758a01129c86f871818a7b4e31c88a3c6b69d9c8319bcbc881b58f067b25"));assert_eq!(Assets.sha2_384(),&hex!("de4656a27347eee72aea1d15e85f20439673709cde5339772660bbd9d800bbde9f637eb3505f572140432625f3948175"));assert_eq!(Assets.sha2_512(),&hex!("bc1673b560316c6586fa1ec98ca5df3e303b66ddae944b05c71314806f88bd4b8f4c7832dfb7dd729eaca191b7142936d21bd07f750c9bc35d67f218e51bbaa4"));assert_eq!(Assets.sha3_224(),&hex!("6949265b40fa55e0c194e3591f90e6cbf0ac100d7ed32e71d6e1e753"));assert_eq!(Assets.sha3_256(),&hex!("a2d99103dc2d1967fb05c4de99a1432e9afb1f5acc698fefb2112ce7fb9335c4"));assert_eq!(Assets.sha3_384(),&hex!("cf1f50cb53dc61b3519227887bfb20230b6878d32b10c5a9bfe016095aaecc593e612a165c89488109da62138a7214d8"));assert_eq!(Assets.sha3_512(),&hex!("aeff4601a53fecdad418f3245676398719d507bd7b971098ad3f4c2d495c2cc96faf022f481c0bebc0632492abd8eb9fe9f8af6d25664f33d61ff316d269682a"));assert_eq!(Assets.blake3_256(),&hex!("b5947e2140b0fe744b1afe9a9f9031e72571c85db079413a67b4a9309f581de7"));}}
 Compression traits
You can use any combination of compression traits on a file. It stores compressed content with provided algorythm.
It might help you to use in a case like providing static content from a web server - you can analyze Accept header and use it to provide various Content-Encoding and body. See it in examples.
The feature is not designed to reduce the size, but to have the already compressed content. If you want to reduce bin size you should consider compressing entire binary.
DeriveRequired featureTraitCompression settings
Zstdzstd[crate::ZstdContent]Compression level = 19
Gzipgzip[crate::GzipContent]Compression level = 9
Brotlibrotli[crate::BrotliContent]Compression level = 11, LZ77 window size = 22
#[cfg( all( feature = "zstd", feature = "gzip", feature = "brotli",))]mod lib {use std::str::from_utf8;#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", file( derive(Zstd), derive(Gzip), derive(Brotli),),)]pubstructAssets;fnmain(){use hex_literal::hex;assert_eq!(Assets.hello().gzip_content(),&hex!("1f8b08000000000002ffcb48cdc9c9070086a6103605000000"));assert_eq!(Assets.hello().zstd_content(),&hex!("28b52ffd008829000068656c6c6f"));assert_eq!(Assets.hello().brotli_content(),&hex!("0b028068656c6c6f03"));}}
More complex example
#[derive(embed_it::Embed)]#[embed( path = "$CARGO_MANIFEST_DIR/../example_dirs/assets", dir(// trait name for directories (default `Dir`) trait_name = AssetsDir,// trait name for directory field's factories (default `DirFieldFactory`) field_factory_trait_name = AssetsDirFieldFactory,// Do not derive default traits for a dir derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `Entries` trait, which stores all direct children into an array derive(Entries),// implement `Index` trait, which stores (recursively) all children into a set derive(Index),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `std::fmt::Debug` for directory. It writes each child implementing debug derive(Debug), field( name = children, trait_name = AssetsChildrenField, factory = Children, pattern = "?*", regex = ".+",), field( name = root_children, trait_name = AssetsRootChildrenField, factory = Children,// only for `Assets` regex = "",),), file(// trait name for files (default `File`) trait_name = AssetsFile,// trait name for file field's factories (default `FileFieldFactory`) field_factory_trait_name = AssetsFileFieldFactory,// Do not derive default traits for a file derive_default_traits = false,// implement embed_it::EntryPath derive(Path),// implement `embed_it::Meta` trait, which provides metadata of the entry derive(Meta),// implement `embed_it::Content` trait, which provides content of the file as a byte array derive(Content),// implement `std::fmt::Debug` for a file. It writes Content len derive(Debug), field(// The name of the method of the trait name = as_str,// The trait name, defaul `"{name.to_pascal()}Field"` trait_name = AssetsAsStrField,// The factory to create an instance of the field factory = AsStr,// The pattern to match entry's path. Default None pattern = "*.txt",// The regex to match entry's path. Default None regex = ".+",),),// `Entry` - enum with `Dir(&'static dyn Dir)/File(&'static dyn File)` variants// `Entry` implements intersection of `Dir`'s and `File`'s traits entry(// struct name for a param of the `Entry::Dir()`. Default `DynDir` dir_struct_name = DynDir,// struct name for a param of the `Entry::File()`. Default `DynDir` file_struct_name = DynFile,// trait name for a trait which is combination of the `Dir` and all `global` fields. Default `EntryDir` dir_trait_name = EntryDir,// trait name for a trait which is combination of the `File` and all `global` fields. Default `EntryFile` file_trait_name = EntryFile,),// if true, the macro will use the extension as a part of `StructName`s and `method_name`s// e.g. hello.txt turns into HelloTxt/hello_txt() if with_extension = true, and Hello/hello() if with_extension = false// default is false with_extension = true,)]pubstructAssets;pubstructChildren;// The name of the factory as in the attribute `dir`implAssetsDirFieldFactoryforChildren{typeField = Vec<&'staticstr>;fncreate<T:AssetsDir + ?Sized>(data:&T) -> Self::Field{
data.entries().iter().map(|v| v.map(|d| d.path(), |f| f.path()).value().relative_path_str()).collect()}}pubstructAsStr;// The name of the factory as in the attribute `file`implAssetsFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:AssetsFile + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}fnmain(){use embed_it::Entry;assert_eq!(Assets.hello_txt().as_str(),&Some("hello"));assert_eq!(Assets.one_txt_1().as_str(),&Some("one"));assert_eq!(Assets.world_txt().as_str(),&Some("world"));assert_eq!(Assets.one_txt().hello().content(),b"hello");assert_eq!(Assets.one_txt().world().content(),b"world");assert_eq!(Assets.one_txt().children(),&vec!["one_txt/hello","one_txt/world"]);let entries:&'static[Entry<_,_>] = Assets.entries();for entry in entries {println!("relative_path: {:?}", entry.map(|d| d.path(), |f| f.path()).value().relative_path_str());println!("{:?}", entry.map(|d| d.metadata(), |f| f.metadata()).value());println!("{:#?}", entry);}}
How does fs-entry's name turn into Rust identifiers?
Each name will be processed and any unsuitable symbol will be replaced with _. This might cause a problem with a level uniqueness of identifiers, for example, all of the entry names below turn into one_txt.
  • one+txt
  • one-txt
  • one_txt
The macro handles this problem and generates methods with a numeric suffix. In that case it would be
  • one+txt - one_txt()
  • one-txt - one_txt_1()
  • one_txt - one_txt_2()
Entries are sorted unambiguously by entry kind (directories first, then files) and subsequently by path.
This works for struct names in the same way
  • one+txt - OneTxt
  • one-txt - OneTxt1
  • one_txt - OneTxt2
What code will be generated by macros
  1. The macro generates definitions for traits Dir and File where each is a compilation of the all derived traits
  2. The macro generates definitions for traits EntryDir and EntryFile where each is a compilation of a previous step trait and the all field traits with global
  3. The macro generates structs DynDir(&'static dyn EntryDir) and DynFile(&'static dyn EntryFile) which is used for dynamic dispatch (like Entries or Index traits).
  4. The macro implements the intersection of the Dir and File traits for the Entry struct
  5. The macro generates traits for FileFieldFactory and DirFieldFactory with bounds to File/Dir traits for the argument of the method
  6. The macro generates traits for each field
  7. For any entry starting from the root:

    • For each type of entry, the macro implements the requested suitable embedded traits (like Content, Path, Metadata, Entries, Index, etc.)
    • For each type of entry, the macro implements traits for all suitable fields from the step 6
    • For a directory, the macro recursively generates code for each child
NOTE: All instances are static, and this staticness is achieved
  • by const for any const items, like file content or file path
structHello;#[automatically_derived]impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{constVALUE:&[u8] = b"hello";// in a real-world scenario, it would be `include_bytes!(...)`VALUE}}
  • by a staticLazyLock for non-const items, which can be created without a context
use embed_it::Entry;pubstructAssets;pubtraitDir:Send + Sync + Index<EntryDir,EntryFile>{}pubtraitFile:Send + Sync + Content{}pubstructEntryDir(&'staticdynDir);pubstructEntryFile(&'staticdynFile);#[automatically_derived]implIndex<EntryDir,EntryFile>forAssets{fnget(&self,path:&str) -> Option<&'staticEntry<EntryDir,EntryFile>>{staticVALUE:::std::sync::LazyLock<::std::collections::HashMap<&'staticstr,Entry<EntryDir,EntryFile>,>,> = ::std::sync::LazyLock::new(|| {letmut map = ::std::collections::HashMap::with_capacity(2usize);// inserts
map
});VALUE.get(path)}}
  • by a staticOnceLock for non-const items, which require a context (like additional fields)
// user-defined struct and implementationpubstructAsStr;implFileFieldFactoryforAsStr{typeField = Option<&'staticstr>;fncreate<T:File + ?Sized>(data:&T) -> Self::Field{
std::str::from_utf8(data.content()).ok()}}pubstructAssets;// auto-generatedpubtraitDir:Send + Sync{}pubtraitFile:Send + Sync + ::embed_it::Content{}pubstructHello;impl::embed_it::ContentforHello{fncontent(&self) -> &'static[u8]{// Some implementationunimplemented!();}}implFileforHello{};pubenumEntry{Dir(&'staticdynDir),File(&'staticdynFile),}pubtraitFileFieldFactory{typeField;fncreate<T:File + ?Sized>(data:&T) -> Self::Field;}pubtraitAsStrField{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field;}#[automatically_derived]implAsStrFieldforHello{fnas_str(&self,) -> &'static <AsStrasFileFieldFactory>::Field{staticVALUE:::std::sync::OnceLock<
<AsStrasFileFieldFactory>::Field,> = ::std::sync::OnceLock::new();VALUE.get_or_init(|| {
<AsStrasFileFieldFactory>::create(self)})}}
About
Include your assets statically into your application with a strict structure
Resources
Readme
MIT license
Activity
Stars
94 stars
Watchers
2 watching
Forks
3 forks
Report repository
Releases
Packages
Contributors
Languages