Resource Embedding in C++

Embedding resources directly into a C++ binary is a practical way to improve performance, enhance startup reliability, and make small tools more portable. In this project, I present a minimal, reproducible approach: converting any text file into a C header with a byte array at build time, compiling that header into the executable, and managing the build tools and dependencies with Conan 2. The following notes explain why you might choose this pattern, how it maps to the rest of this proof-of-concept, and what trade-offs to consider.

Overview

Why embed a resource?

• Single artifact deployment: Shipping one executable avoids issues with missing files and path handling on different platforms.
• Deterministic access: Embedded bytes are available immediately at startup without requiring I/O or relative-path resolution.
• Useful for constrained targets: Embedded assets are particularly handy on embedded devices, containers, or environments where the filesystem is read-only or restricted.
• Reproducible builds: Generating resources at build time ensures the binary contains exactly the intended resource version.

How this proof-of-concept works (high level)

• A custom build step runs a tool (e.g., xxd in this proof-of-concept) to convert src/schema.txt into a C header that defines a byte array (e.g., unsigned char SCHEMA[] and unsigned int SCHEMA_len).
• The generated header is written into the build directory and added to the target compile sources. The target includes the build directory so the generated header is found by the compiler.
• The final executable accesses the array directly in memory, eliminating the need for separate file reads at runtime.

Implementation Example

Conan

Technically, this approach does not rely on Conan. However, Conan can be beneficial if the tools you use are managed by it. For simplicity, this example omits such integration and uses Conan primarily as a wrapper around CMakeLists.txt, given its popularity as a package manager.

Here is a minimal Conan 2 configuration:

1
from conan import ConanFile
2
from conan.tools.cmake import CMakeToolchain, CMake, cmake_layout
3

4
class SchemaPocConan(ConanFile):
5
    name = "schema_poc"
6
    version = "1.0"
7
    settings = "os", "compiler", "build_type", "arch"
8
    generators = "CMakeDeps", "CMakeToolchain"
9
    exports_sources = "src/*", "CMakeLists.txt"
10

11
    def layout(self):
12
        cmake_layout(self)
13

14
    def build(self):
15
        cmake = CMake(self)
16
        cmake.configure()
17
        cmake.build()

Good ol' CMake

The idea is to generate a header file (here schema.hpp), that is generated at build time and compiled into the binary to provide a SCHEMA bute array, which we can then use in our code.

1
cmake_minimum_required(VERSION 3.15)
2
project(schema_poc)
3

4
add_executable(schema_poc src/main.cpp)
5

6
add_custom_command(
7
    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/schema.hpp
8
    COMMAND xxd -n "SCHEMA" -i ${CMAKE_CURRENT_SOURCE_DIR}/src/schema.txt > ${CMAKE_CURRENT_BINARY_DIR}/schema.hpp
9
    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/src/schema.txt
10
)
11

12
target_include_directories(schema_poc PRIVATE ${CMAKE_BINARY_DIR})
13
target_sources(schema_poc PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/schema.hpp)

This is a minimal example of a CMakeLists.txt that generates an executable. Notice the add_custom_command, which is where all the magic really happens:

• Line 8: Run xxd to convert src/schema.txt into a C header defining SCHEMA and SCHEMA_len, writing to the build dir.
• Line 9: Make the custom command re-run when the schema source changes.
• Line 12: Add the build directory to the include path so the generated header is found at compile time.
• Line 13: Add the generated header as a target source so CMake knows to run the custom command and include the file in the build.

How to use it in C++

How you use your assets is up to you.

In my case, schema.txt contains a single ascii word. In the following program, we grab the first argument and check wether it is equal to the word provided by the schema.

1
#include <iostream>
2
#include <cstring>
3

4
#include "schema.hpp"
5

6
int main(int argc, char** argv) {
7
    if (argc > 1 && strcmp(argv[1], reinterpret_cast<const char*>(SCHEMA)) == 0) {
8
        std::cout << "equal" << std::endl;
9
        return 0;
10
    }
11

12
    std::cerr << "not equal" << std::endl;
13
    return 1;
14
}

Limitations

While the tool I used (xxd) is very handy for such tasks, yet it is not a Conan package at the moment. So integration with certian CI workflows or cross-compilation environments might become tricky.

An alternative would be to manually have a script that does effectively the same, which can than be tracked as part of the project or integrated with Conan as a dependency.