Advanced Resource Embedder

TL;DR

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);

Version 1.3 - Aug 2023

• Fix #3: Allow to keep empty lines when content is split

List all versions

Overview

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 gzip or 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.

Examples

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

Building ARE

To build the ARE you will need the GNAT Ada compiler, either the FSF version available in Debian, FreeBSD systems, NetBSD or the AdaCore GNAT Community 2021 edition. Because there exists different versions of the compiler, you may have to adapt some of the commands proposed below for the installation.

Development Host Installation

Ubuntu 22.04

Install the following packages:

sudo apt install -y make git
sudo apt install -y gnat gprbuild libxmlada-dom10-dev

Ubuntu 20.04

Install the following packages:

sudo apt install -y make git
sudo apt install -y gnat-9 gprbuild libxmlada-dom9-dev

FreeBSD 13

Install the following packages:

pkg install gmake gnat12 gprbuild git

Windows

Get the Ada compiler from AdaCore Download site and install.

Install the following packages:

pacman -S git
pacman -S make
pacman -S base-devel --needed

Getting the sources

The project uses a sub-module to help you in the integration and build process. You should checkout the project with the following commands:

git clone --recursive https://gitlab.com/stcarrez/resource-embedder.git
cd resource-embedder

Configuration (optional)

Running the configure script is optional To configure the resource embedder, use the following command:

./configure

Build

To build the resource embedder, run the command:

make

If you have an old GNAT compiler (gcc < 8) you may build with:

make GNAT_SWITCH=NO_CALLBACK

And install it:

make install

Debian Packages for x86_64

You can install ARE by using the Debian 10 and Ubuntu 20.04 or 18.04 packages. First, setup to accept the signed packages:

wget -O - https://apt.vacs.fr/apt.vacs.fr.gpg.key | sudo tee /etc/apt/trusted.gpg.d/apt-vacs-fr.asc

and choose one of the echo command according to your Linux distribution:

Ubuntu 22.04

echo "deb https://apt.vacs.fr/ubuntu-jammy jammy main" | sudo tee -a /etc/apt/sources.list.d/vacs.list

Ubuntu 20.04

echo "deb https://apt.vacs.fr/ubuntu-focal focal 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

Documents

• Resource Embedder Guide PDF
• Man page: are (1)