Examples » Resource management

Compiling external files into application binary.

The Utility::Resource class provides management of resources compiled directly into the executable, such as icons, data files etc. This tutorial will give you a brief introduction into how resources are compiled into the executable and later retrieved in the application.

Resource compilation

Imagine that you have e.g. a long license text with all these yelling words in all caps:

This application is copyright © John Doe et al. and the author IS NOT
RESPONSIBLE AT ALL FOR ANY PHYSICAL OR OTHER DAMAGES AND INJURIES WHICH
MAY LEAD TO DEATH OR EVEN APOCALYPSE AND CAN BE CAUSED BY THIS APPLICATION
...

And for obvious reasons you don't want to put directly into the code, have it in a separate file, but in the end you want it compiled directly into the executable, so your product is one compact file.

Corrade's CMake support provides the corrade_add_resource(), macro which takes resource configuration file and produces C++ source file. The source file can be then passed among other source files to an executable or a library. First argument is name of resulting C++ source file, second argument is a configuration file name.

find_package(Corrade REQUIRED Utility)
set_directory_properties(PROPERTIES CORRADE_USE_PEDANTIC_FLAGS ON)

corrade_add_resource(Resources resources.conf)

The configuration file contains group name (explained below) and list of all the files. The files can also have aliases for e.g. simplifying filenames.

group=data

[file]
filename=licenses/en.txt
alias=license.txt

[file]
filename=icon.png

Resource management

Now it's time to make an application which will have these resources compiled in. The resources should be initialized automatically, if not (for example if they are compiled into static library), call CORRADE_RESOURCE_INITIALIZE() with resource name as argument before they are used, for example at the beginning of main() function.

This example application will just print the license text and exit:

#include <Corrade/Utility/Debug.h>
#include <Corrade/Utility/DebugStl.h>
#include <Corrade/Utility/Resource.h>

using namespace Corrade;

int main() {
    /* Initialize resource manager with name of the group we are using */
    Utility::Resource rs{"data"};

    /* Print out the license */
    Utility::Debug{} << rs.get("license.txt");
}

Compile the application with simple CMake add_executable() command and don't forget to compile in the resource file created above:

add_executable(ResourceTest main.cpp ${Resources})
target_link_libraries(ResourceTest PRIVATE Corrade::Utility)

After successful compilation the application will print out the license text:

$ ./ResourceTest
This application is copyright © John Doe et al. and the author IS NOT
RESPONSIBLE AT ALL FOR ANY PHYSICAL OR OTHER DAMAGES AND INJURIES WHICH
MAY LEAD TO DEATH OR EVEN APOCALYPSE AND CAN BE CAUSED BY THIS APPLICATION
...

The full file content is linked below. Full source code is also available in the GitHub repository.