The resource embedder allows to embed files in binaries by producing C, Ada or Go source files that contain the original files.
For example to generate a my-config.h and my-config.c files with the content of the
config directory to include files matching the *.conf pattern in any
directory:
are --lang=c -o src --resource=my-config --name-access --fileset='**/*.conf' config
And if you prefer to generate a config.ads and config.adb Ada package with the
resources, you may use:
are --lang=Ada -o src --resource=config --name-access --fileset='**/*.conf' config
Complex resource integrations are best described with and XML and are generated with:
are --lang=Ada -o src --rule=package.xml --name-access .
For Ada, it generates the following package declaration with the Get_Content function
that gives access to the files. The Ada body contains the content of each embedded file.
package Config is
function Get_Content (Name : in String)
return access constant String;
end Config;For C, it generates a C structure that describes each file and a function that gives access to the file content. The C source file contains the content of each embedded file.
struct config_content {
const unsigned char *content;
size_t size;
time_t modtime;
int format;
}
extern const struct config_content *config_get_content(const char* name);- Cleanup build environment and drop configure scripts
Incorporating files in a binary program can sometimes be a challenge.
The Advance Resource Embedder is a flexible tool that collects files such as
documentation, images, scripts, configuration files and generates a source
code that contains these files. It is able to apply some
transformations on the collected files:
- it can run a Javascript minifier such as
closure, - it can compress CSS files by running
yui-compressor, - it can compress files by running
gzipor another compression tool,
Once these transformations are executed, it invokes a target generator to produce a source file either in C, Ada or Go language. The generated source file can then be used in the final program and taken into account during the compilation process of that program. At the end, the binary will contain the embedded files with their optional transformations.
The process to use ARE is simple:
- You describe the resources that you want to embed. The description is either made on command line arguments or by writing an XML file. The XML description gives more flexibility as it allows to define a transformation rule that must be executed on the original file before being embedded. This allows to minify a Javascript or CSS file, compress some files and even encrypt a file before its integration.
- You run the ARE command with your target language and rule description and you give the tool a list of directories that must be scanned to identify the files that must be collected. The ARE tool scan the directories according to the patterns that you have given either on the command line or in the XML rule description. After identifying the files, the tool applies the rules and execute the transformations. The ARE tool then invokes the target language generator that writes one or several files depending on the list of resources.
- Once the files are generated, you use them in your program and add them in your build process as they are now part of your sources. After building your program, it now embeds the resource files that were collected and optionally transformed.
Note:
The generated code is not coverred by any license but because it integrates the resource file, you have to consider the license of these resource file.
This first set of example shows how to you can embed configuration files in a C, Ada or Go program. The Advance Resource Embedder simply puts the configuration files in an array of bytes that can easily be retrieved by a generated function.
- Embedding configuration files in C
- Embedding configuration files in Ada
- Embedding configuration files in Go
A second set of example is more advanced by the use of an XML file that describes what must be embedded with
the transformations that must be made. It creates two distinct resource sets help and man. The help resource
set is composed of a set of fixed documentation files provided in the example. The man resource set is created
by running the man Unix command on various names to embed the man page of ls, pwd and sh.
- Embedding help and documentation in C
- Embedding help and documentation in Ada Embedding help and documentation in Ada (binary)
- Embedding help and documentation in Go
More specific examples show how to make specific transformations on the files before integrating them:
- Embedding web files in C
- Embedding merged properties in Ada
- Embedding SQL scripts in Ada and mapping them in array of String
- Embedding SQL scripts in C and mapping them in array of String
- Embedding mapping tables in Ada
To build the ARE you will need the GNAT Ada compiler, either the FSF version available in Debian, FreeBSD systems, NetBSD.
You can build ARE by using the Alire package manager. Just type:
alr build
To build the ARE you will need the GNAT Ada compiler as well as the Alire package manager.
Install the following packages:
sudo apt install -y make git alire
sudo apt install -y gnat gprbuild
Install the following packages:
pkg install gmake gnat13 gprbuild git alire
Get the Alire package manager Alire site and install.
Install the following packages:
pacman -S git
pacman -S make
pacman -S base-devel --needed
You should checkout the project with the following commands:
git clone https://gitlab.com/stcarrez/resource-embedder.git
cd resource-embedder
To build the resource embedder, run the command:
make
Note that on FreeBSD and NetBSD, you must use gmake instead of make.
And install it:
make install
You can install ARE by using the Debian 12 and Ubuntu 24.04 packages. First, setup to accept the signed packages:
wget -O - https://apt.vacs.fr/apt.vacs.fr.gpg.asc | sudo tee /etc/apt/trusted.gpg.d/apt-vacs-fr.asc
and choose one of the echo command according to your Linux distribution:
Ubuntu 24.04
echo "deb https://apt.vacs.fr/ubuntu-noble noble main" | sudo tee -a /etc/apt/sources.list.d/vacs.list
Debian 12
echo "deb https://apt.vacs.fr/debian-bullseye bullseye main" | sudo tee -a /etc/apt/sources.list.d/vacs.list
Then, launch the apt update command:
sudo apt-get update
and install the tool using:
sudo apt-get install -y are
- Resource Embedder Guide PDF
- Man page: are (1)