# GCR_CMake A CMake extension supporting the **glib-compile-resources** tool. About ----- Inspired from the macros for Vala that I used to build a GTK application, I came to the point where I needed resources for it. For that purpose the **glib-compile-resources** tool seemed to be the right choice, but the extra XML file you need to write bothered me. If I add a resource I don't want to mark it explicitly in CMake and in the XML file. So I came up with this macro that does everything for you. You just add your resource to a resource list (with eventually some attributes like compression) and invoke the resource compilation function. It generates the XML automatically for you. Quite simple, isn't it? Clone ----- To clone this repository, just type ```shell git clone https://github.com/Makman2/GCR_CMake ``` Usage ----- Just add the macro directory to your `CMAKE_MODULE_PATH`, include the CMake file and you are ready to go. ```cmake list(APPEND CMAKE_MODULE_PATH ${PATH_TO_GCR_CMAKE_PARENT_DIR}/GCR_CMake/macros) include(GlibCompileResourcesSupport) ``` Reference --------- The resource compiling macro is quite powerful and handles as much errors as possible to make error-finding easier. The function is defined as follows: ``` compile_gresources( [TYPE output_type] [TARGET output_name] [RESOURCES [resources...]] [OPTIONS [command_line_options...]] [PREFIX resource_prefix] [C_PREFIX c_names_prefix] [SOURCE_DIR resource_directory] [COMPRESS_ALL] [NO_COMPRESS_ALL] [STRIPBLANKS_ALL] [NO_STRIPBLANKS_ALL] [TOPIXDATA_ALL] [NO_TOPIXDATA_ALL]) ``` - ***output*** The variable name where to set the output file names. Pass this variable to a target as a dependency (i.e. `add_custom_target`). - ***xml_out*** The variable name where to store the output file name of the intermediately generated gresource-XML-file. - **TYPE** ***output_type*** The resource type to generate. Valid values are `EMBED_C`, `EMBED_H`, `BUNDLE` or `AUTO`. Anything else will default to `AUTO`. - `EMBED_C`: Generate a C code file that can be compiled with your program. - `EMBED_H`: Generate a header file to include in your program. - `BUNDLE`: Generates a resource disk file to load at runtime. - `AUTO` (or anything else): Extract mode from file ending specified in `TARGET`. If `TARGET` contains an invalid file or file ending not detectable, the function results in a **FATAL_ERROR**. Recognized file formats are: *.gresource*, *.c*, *.h*. - **TARGET** ***output_name*** Overrides the default output file name. If not specified (and not `AUTO`-**TYPE** is set) the output name is *resources.[type-ending]*. - **RESOURCES** ***[resources...]*** The resource list to process. Each resource must be a relative path inside the source directory. Each file can be preceded with resource flags. - `COMPRESS` flag Compress the following file. Effectively sets the attribute *compressed* in the XML file to true. - `STRIPBLANKS` flag Strip whitespace characters in XML files. Sets the *preprocess* attribute in XML with *xml-stripblanks* (requires XMLLint). - `TOPIXDATA` flag Generates a pixdata ready to use in Gdk. Sets the *preprocess* attribute in XML with *to-pixdata*. Note: Using `STRIPBLANKS` and `TOPIXDATA` together results in a **FATAL_ERROR**. - **OPTIONS** ***command_line_options*** Extra command line arguments passed to **glib_compile_resources**. For example `--internal` or `--manual-register`. - **PREFIX** ***resource_prefix*** Overrides the resource prefix. The resource entries get inside the XML a prefix that is prepended to each resource file and represents as a whole the resource path. - **C_PREFIX** ***c_names_prefix*** Specifies the prefix used for the C identifiers in the code generated when *EMBED_C* or *EMBED_H* are specified for *TYPE*. - **SOURCE_DIR** ***resource_directory*** The source directory where the resource files are. If not overridden, this value is set to `CMAKE_CURRENT_SOURCE_DIR`. - **COMPRESS_ALL**, **NO_COMPRESS_ALL** Overrides the `COMPRESS` flag in all resources. If **COMPRESS_ALL** is specified, `COMPRESS` is set everywhere regardless of the specified resource flags. If **NO_COMPRESS_ALL** is specified, compression is deactivated in all resources. Specifying **COMPRESS_ALL** and **NO_COMPRESS_ALL** together results in a **FATAL_ERROR**. - **STRIPBLANKS_ALL**, **NO_STRIPBLANKS_ALL** Overrides the `STRIPBLANKS` flag in all resources. If **STRIPBLANKS_ALL** is specified, `STRIPBLANKS` is set everywhere regardless of the specified resource flags. If **NO_STRIPBLANKS_ALL** is specified, stripping away whitespaces is deactivated in all resources. Specifying **STRIPBLANKS_ALL** and **NO_STRIPBLANKS_ALL** together results in a **FATAL_ERROR**. - **TOPIXDATA_ALL**, **NO_TOPIXDATA_ALL** Overrides the `TOPIXDATA` flag in all resources. If **TOPIXDATA_ALL** is specified, `TOPIXDATA` is set everywhere regardless of the specified resource flags. If **NO_TOPIXDATA_ALL** is specified, converting into pixbufs is deactivated in all resources. Specifying **TOPIXDATA_ALL** and **NO_TOPIXDATA_ALL** together results in a **FATAL_ERROR**. Kickstart --------- This is a quick start guide to provide you an easy start with this macro. Starting with a simple example: ```cmake set(RESOURCE_LIST info.txt img/image1.jpg img/image2.jpg data.xml) compile_gresources(RESOURCE_FILE XML_OUT TYPE BUNDLE RESOURCES ${RESOURCE_LIST}) ``` What does this snippet do? First it sets some resource files to pack into a resource file. They are located in the source directory passed to CMake at invocation (`CMAKE_CURENT_SOURCE_DIR`). After that we compile the resources. Means we generate a *.gresource.xml*-file (it's path is put inside the `XML_OUT` variable) automatically from our `RESOURCE_LIST` and create a custom command that compiles the generated *.gresource.xml*-file with the provided resources into a resource bundle. Since no specific output file is specified via **TARGET** the output file is placed into the `CMAKE_CURENT_BINARY_DIR` with the name *resources.gresource*. The first argument `RESOURCE_FILE` is a variable that is filled with the output file name, so with *resources.gresource* inside the build directory. This variable is helpful to create makefile targets (or to process the output file differently). So here comes a full *CMakeLists.txt* that creates the resources from before. ```cmake # Minimum support is guaranteed for CMake 2.8. Everything below needs to be # tested. cmake_minimum_required(2.8) project(MyResourceFile) # Include the extension module. list(APPEND CMAKE_MODULE_PATH ${PATH_TO_GCR_CMAKE_PARENT_DIR}/GCR_CMake/macros) include(GlibCompileResourcesSupport) # Set the resources to bundle. set(RESOURCE_LIST info.txt img/image1.jpg img/image2.jpg data.xml) # Compile the resources. compile_gresources(RESOURCE_FILE XML_OUT TYPE BUNDLE RESOURCES ${RESOURCE_LIST}) # Add a custom target to the makefile. Now make builds our resource file. # It depends on the output RESOURCE_FILE. add_custom_target(resource ALL DEPENDS ${RESOURCE_FILE}) ``` A nice feature of the `compile_gresources`-macro is that it supports individually setting flags on the resources. So we can extend our resource list like that: ```cmake set(RESOURCE_LIST info.txt COMPRESS img/image1.jpg COMPRESS img/image2.jpg STRIPBLANKS data.xml) ``` This resource list not only simply includes the resources, it specifies also that the two images should be compressed and in *data.xml* the whitespaces should be removed. This resource list will include the same files but will preprocess some of them. Very handy are the `COMPRESS_ALL`, `STRIPBLANKS_ALL` or `TOPIXDATA_ALL` parameters (and their `NO_`-equivalents). If you are too lazy to write before every file the flag, just invoke `compile_gresources` with them. ```cmake # Compile the resources. Compresses all files regardless if you specified it # explicitly or not. compile_gresources(RESOURCE_FILE XML_OUT TYPE BUNDLE RESOURCES ${RESOURCE_LIST} COMPRESS_ALL) ``` So that's a short introduction into the operating mode of the `compile-gresources` macro.