# 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](https://crates.io/crates/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
```rust
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:
```plaintext
embed/
├── ARRAY_ONE.bin
├── ARRAY_TWO.bin
embed.rs
```
### Generated Rust File
The `embed.rs` file will look like this:
```rust
// 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:
```rust
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`](https://crates.io/crates/embed-resources)
If your use case involves embedding files, content from URLs, or arbitrary data with optional compression, consider using the [`embed-resources`](https://crates.io/crates/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`](https://crates.io/crates/embed-resources) crate for more advanced embedding functionality.
### Other Related
- https://stackoverflow.com/questions/75676449/how-to-build-and-publish-a-crate-containing-generated-code
- https://github.com/rust-lang/cargo/issues/12456
- https://github.com/rust-lang/cargo/issues/9398
- https://github.com/pyrossh/rust-embed
## License
[MIT License](LICENSE) (c) 2025 Jeremy Harris.