diff --git a/docs/docs/index.md b/docs/docs/index.md index 676b279..a47b7ad 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -13,6 +13,7 @@ The Brisk library is in the beta stage, so there may be breaking changes, and th ## Core Concepts * [Data Binding](binding.md) +* [Resources](resources.md) ## Examples diff --git a/docs/docs/resources.md b/docs/docs/resources.md new file mode 100644 index 0000000..ad5b8f3 --- /dev/null +++ b/docs/docs/resources.md @@ -0,0 +1,57 @@ +# Resources + +Any files required for the application to run can be embedded directly into the executable as resources. +Common examples include fonts and images, but any file type is supported. + +The embedded resources are stored in the read-only data section of the resulting binary. +Optionally, compression can be applied to reduce the final executable size. + +Resources are stored with associated keys (similar to file paths), which are used to load them at runtime. + +Each CMake target can define its own resources by specifying a unique key, the input file path, and optionally, compression. + +If a target depends on another target, it can override a specific resource by providing a different file path under the same key. +During the linking process, Brisk traverses the dependency tree and collects the list of resources to bundle into the executable. + +## Example Usage + +### CMake Configuration + +```cmake +add_library(utilities utilities.cpp) + +# Add a resource named 'table' from 'data/table.csv' and compress it using Brotli. +brisk_target_resource(utilities table INPUT data/table.csv BROTLI) + +add_executable(main main.cpp) + +# Add an icon from 'icon.png' as a resource. +brisk_target_resource(main icon INPUT icon.png) + +target_link_libraries(main PRIVATE utilities) + +# Must be placed after brisk_target_resource to bundle all resources into the executable. +brisk_bundle_resources(main) +``` + +### C++ Code + +In C++, you can load any resource bundled with the executable using `loadResource` or `loadResourceText`: + +```c++ +#include +#include + +// Load the icon resource and decode it into an image. +RC loadIcon() { + // Assume the resource exists and ignore errors for simplicity. + return imageDecode(loadResource("icon"), ImageFormat::RGBA).value(); +} + +void loadTable() { + // Load the 'table' resource as a text string. + std::string t = loadResourceText("table"); + + // Process the table data... +} +```