6 stable releases
1.1.4 | Dec 1, 2023 |
---|---|
1.1.3 | Oct 26, 2023 |
1.1.2 | Apr 3, 2023 |
1.1.0 | Mar 31, 2023 |
#212 in Development tools
20KB
319 lines
embin
A simple program that can embed binary or text files into source code of a specific language
Installation
You can find pre-built releases for linux
, macOS
and Windows
Otherwise, you can install embin
from source using cargo, with the following command:
cargo install embin
⭐ Don't forget to put a star if you like the project!
Usage
Usage: embin [OPTIONS] <INPUT>...
Arguments:
<INPUT>... Input file(s) to embed, which can be binary or text files
Options:
-o, --output <OUTPUT> Write generated source code in output file instead of stdout
--lang <LANG> Language of the generated source code [default: c]
--format <FORMAT> Format of the generated source code [default: hex]
--indent <INDENT> Indentation type of the generated source code [default: space]
--padding <PADDING> Padding value of the generated source code [default: 4]
--quantity <QUANTITY> Number of byte elements per line [default: 16]
--mutable Make generated variables mutable
-h, --help Print help
-V, --version Print version
Examples
Embedding a file into C
embin --lang=c data.png > output.h
Result:
const unsigned char data_png[] = {
0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65,
0x73, 0x74, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68,
0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x6e, 0x65, 0x77, 0x20,
0x6c, 0x69, 0x6e, 0x65, 0x2e, 0x0a
};
const unsigned int data_png_len = 42;
Embedding a file into C++
embin --lang=cpp data.png > output.hpp
Result:
#include <array>
constexpr std::array<unsigned char, 42> data_png = {
0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65,
0x73, 0x74, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68,
0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x6e, 0x65, 0x77, 0x20,
0x6c, 0x69, 0x6e, 0x65, 0x2e, 0x0a
};
Embedding a file into Python
embin --lang=python data.png > output.py
Result:
DATA_PNG = bytes([
0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65,
0x73, 0x74, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68,
0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x6e, 0x65, 0x77, 0x20,
0x6c, 0x69, 0x6e, 0x65, 0x2e, 0x0a
])
⚠️ On Windows, use
--output
instead of>
when generating your embedded assets to avoid the following error when running python code:
source code string cannot contain null bytes
Embedding multiple files
embin --lang=cpp assets/icon.png assets/banner.png > assets.hpp
Result:
#include <array>
constexpr std::array<unsigned char, 42> icon_png = {
0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65,
0x73, 0x74, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68,
0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x6e, 0x65, 0x77, 0x20,
0x6c, 0x69, 0x6e, 0x65, 0x2e, 0x0a
};
constexpr std::array<unsigned char, 86> banner_png = {
0x69, 0x73, 0x20, 0x61, 0x20, 0x6e, 0x65, 0x77, 0x20, 0x6c, 0x69, 0x6e,
0x65, 0x2e, 0x0a, 0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61,
0x20, 0x74, 0x65, 0x73, 0x74, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a,
0x0a, 0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x6e,
0x65, 0x77, 0x20, 0x6c, 0x69, 0x6e, 0x65, 0x2e, 0x0a, 0x54, 0x68, 0x69,
0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65, 0x73, 0x74, 0x20,
0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68, 0x69, 0x73, 0x20,
0x73, 0x20
};
Options
--format
Set the format of the generated source code
Char
format:
embin --format=char data.txt
const unsigned char data_txt[] =
"This is a test file.\n\n"
"This is a new line.\n";
const unsigned int data_txt_len = 42;
Octal
format:
embin --format=octal data.txt
const unsigned char data_txt[] =
"\124\150\151\163\040\151\163\040\141\040\164\145\163\164\040\146"
"\151\154\145\056\012\012\124\150\151\163\040\151\163\040\141\040"
"\156\145\167\040\154\151\156\145\056\012";
const unsigned int data_txt_len = 42;
--indent
Set indentation type of the generated source code
Indent with tabs instead of spaces:
embin --indent=tab data.png
--padding
Set padding value of the generated source code
embin --padding 0 data.png
const unsigned char data_png[] = {
0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65,
0x73, 0x74, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68,
0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x6e, 0x65, 0x77, 0x20,
0x6c, 0x69, 0x6e, 0x65, 0x2e, 0x0a
};
const unsigned int data_png_len = 42;
--quantity
Set number of byte elements per line
embin --quantity 8 data.png
const unsigned char data_png[] = {
0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20,
0x61, 0x20, 0x74, 0x65, 0x73, 0x74, 0x20, 0x66,
0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68,
0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20,
0x6e, 0x65, 0x77, 0x20, 0x6c, 0x69, 0x6e, 0x65,
0x2e, 0x0a
};
const unsigned int data_png_len = 42;
--mutable
Make generated variables mutable
embin --mutable data.png
unsigned char data_png[] = {
0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65,
0x73, 0x74, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x2e, 0x0a, 0x0a, 0x54, 0x68,
0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x6e, 0x65, 0x77, 0x20,
0x6c, 0x69, 0x6e, 0x65, 0x2e, 0x0a
};
unsigned int data_png_len = 42;
License
This project is released under MIT license.
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Dependencies
~1–11MB
~75K SLoC