embed-bytes 0.1.0-alpha6

A simple Rust crate to embed assets.
Documentation

embed-bytes (Work in Progress)

This is a prototype; the documentation may not be correct, and the API is subject to change.

embed-bytes is a Rust crate that simplifies embedding low-level binary arrays and assets in other Rust programs. It relies only on the bytes crate for efficient handling of these assets.

When used in a build.rs script, embed-bytes operates as a zero-cost abstraction, as all processing occurs at compile-time. The embedding directory is automatically created during the build process, where asset names are converted into .bin files, and a Rust source file is generated to include these assets using include_bytes!.

Usage Example

Writing Byte Arrays to Files and Generating a Rust File

The write_byte_arrays function makes it easy to embed byte arrays into your Rust project. It generates .bin files for each byte array and creates a corresponding .rs file with include_bytes! references for seamless integration.

Example

use bytes::Bytes;
use std::path::Path;
use build_resource_byte_arrays::write_byte_arrays;

fn main() -> std::io::Result<()> {
    // Define the output directory
    let output_dir = Path::new("embed");

    // Define the byte arrays to write
    let byte_arrays = vec![
        ("ARRAY_ONE", Bytes::from(vec![1, 2, 3, 4])),
        ("ARRAY_TWO", Bytes::from(vec![5, 6, 7, 8])),
    ];

    // Write the byte arrays and generate the Rust file
    write_byte_arrays(output_dir, byte_arrays)?;

    println!("Byte arrays written to 'embed/' and Rust file 'embed.rs' generated.");
    Ok(())
}

Output

If the output directory is specified as embed, the following files will be created:

embed/
├── ARRAY_ONE.bin
├── ARRAY_TWO.bin
embed.rs

Generated Rust File

The embed.rs file will look like this:

// Automatically generated file. Do not edit.
// Generated by embed-bytes crate.

pub static ARRAY_ONE: &[u8] = include_bytes!("embed/ARRAY_ONE.bin");
pub static ARRAY_TWO: &[u8] = include_bytes!("embed/ARRAY_TWO.bin");

Notes

  • The function will create the embed directory if it does not already exist.
  • It will sanitize invalid characters in the directory name to ensure the generated .rs file is valid in Rust.
  • To use the generated .rs file, include it in your project with a mod statement: 
    mod embed;
use embed::{ARRAY_ONE, ARRAY_TWO};

fn main() {
    println!("ARRAY_ONE: {:?}", ARRAY_ONE);
    println!("ARRAY_TWO: {:?}", ARRAY_TWO);
}

Error Handling

The function will return an error if:

  • The specified directory name is invalid (e.g., starts with a digit).
  • A file operation (e.g., creating or writing files) fails.

Related

Related Crate: embed-resources

If your use case involves embedding files, content from URLs, or arbitrary data with optional compression, consider using the embed-resources crate. It provides a higher-level API for handling such scenarios, building on the functionality offered by this crate.

For example:

  • Embedding files from a directory.
  • Fetching and embedding content from URLs.
  • Compressing the data before embedding it.

Check out the embed-resources crate for more advanced embedding functionality.

Other Related

License

MIT License (c) 2025 Jeremy Harris.