libs/EXTERNAL/libezgl/gcr-cmake/README.md

# 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(<output>
                   <xml_out>
                   [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.