Assets (resource compiler) is a platform-agnostic feature provided by aui.toolbox that embeds external files to the application's or library's binary, making them available from C++ regardless of file environment. You may want to use this if you need resources such as images, sounds or any other types of files to avoid the complexity of platform-specific means to package and locate those files.

This makes the application self-contained and reduces the surface of attack for your application and resources, as they can't be viewed or changed as easily as files lying around in user's filesystem.

To refer to an asset file, prefix the path with colon character. See AUrl for more info.

aui_compile_assets#

Assets can be enabled for your target with aui_compile_assets function in your CMakeLists.txt:

project(aui.example.notes)
cmake_minimum_required(VERSION 3.16)
 
# Uncomment this code to pull AUI:
#
# file(
#         DOWNLOAD
#         https://raw.githubusercontent.com/aui-framework/aui/master/aui.boot.cmake
#         ${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
# include(${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
#
# auib_import(aui https://github.com/aui-framework/aui
#             COMPONENTS core views json)
 
aui_executable(aui.example.notes)
aui_compile_assets(aui.example.notes)
 
aui_link(aui.example.notes PUBLIC aui::core aui::views aui::json)
 

Then, create assets directory alongside with CMakeLists.txt:

mkdir assets

Put your files to that dir:

cp test.txt assets/test.txt

Note: Please invoke CMake configure each time you add/remove files in assets/! Otherwise, these files will not appear in your program.
cd build

cmake .. # no need to pass arguments in existing build dir

From now, you can use the file from C++.

":background.png"_url.open()

_new<AView>() with_style {
  BackgroundImage { ":background.png" },
},

See also Minimal UI Template with Assets for a complete minimal example.

How does it work#

aui_compile_assets adds a build time dependency to the specified target on aui.toolbox that generates C++ files per each file found in assets/ directory. Those *.cpp files are compiled along with your target. C++ files contain a byte array that is being registered automatically to AUI's ABuiltinFiles filesystem.

aui.toolbox applies several transformations on a file before putting it into the *.cpp:

Compresses the data. Although it may be redundant for already compressed file formats such as *.png, it provides a decent compression ratio for textual files, such as *.svg.

Also, this makes it harder to reverse engineer asset files from your binary. This is not entirely impossible, but thanks to the compression, textual files that appear in AUI assets can't be extracted with Windows Notepad.
Converts data to HEX string.

Contents