CMake Resource Library

Embed a whole directory tree into a C++ source file. Easy access from C++ code is provided. No dynamic memory allocations.

Usage in CMakeLists.txt:

# Add the resource library
add_subdirectory("${PATH_TO_CMAKE_RESOURCE_LIBRARY}")
add_resource_library(assets "${ASSETS_BASE_DIR}")

# Use it wherever it's needed
add_executable(example "main.cpp")
target_link_libraries(example PRIVATE assets)

This creates a cmake library which contains all the files contained in the provided directory which then can be used from C++ code.

#include <assets.h>

int main() {
    // get asset using a string_view as key
    std::optional<std::span<std::byte>> ok_icon = assets::get_file("icons/cross.png");

    // get asset using a path broken apart over multiple string_views (span<string_view>)
    std::array<std::string_view, 4> path = {"icons", "/", "cross", ".png"};
    std::optional<std::span<std::byte>> ok_icon = assets::get_filev(path);

    // For development hot-reload with a similar interface is provided
    crl::HotReloader hot_reloader("/home/dev/assets");
    std::optional<std::span<std::byte>> ok_icon = hot_reloader.get("icons/cross.png")
}

Features

• No dynamic memory allocations
• Re-build automatically when content of source directory changes
• Optional: Perfect hash getter function using gperf
• Optional: Hot reload for development crl hot reload (Allocating!)

Prerequisites

• CMake 3.17 or higher
• C++20 compatible compiler

License

This project is licensed under the MIT License.

Installation

This project is CMake based and can be consumed in the typical ways:

• Include project as git submodule crl and use add_subdirectory(crl)
• Use fetch_content to obtain the library on build time
• ...

Architecture

This project consists of several components:

• CMake component lib/cmake: provides the "add_resource_library" cmake function, which creates a CMake library target which depends on the files generated by a custom_command. This custom_command calls the lib/cmake/generate.cmake in scripting mode which does the heavy lifting.
• The main library lib/crl: Defines some types and provides functionality which is used by resource libraries.
• The crl_hot_reload library: Add-on which should only be used for development. More details here: crl hot reload.

This project consists of several components:

• CMake Component (lib/cmake): This component provides the add_resource_library CMake function, which creates a CMake library target depending on the files generated by a custom CMake command. This command calls the lib/cmake/generate.cmake script to generate the required C++ source files.

• Main Library (lib/crl): The core of the project, this library defines types and functions for accessing the embedded resources from C++.

• Hot Reload Add-on (lib/crl_hot_reload): This optional add-on enables hot-reloading of assets during development. It should only be used in a development environment and allows you to reload assets without rebuilding the application. More details here: crl hot reload

Development

Additional features that might be nice to have:

• C interface
• Maybe C++ interfaces < C++20