This category includes CMake utility functions for external projects. More...

Functions
	usFunctionAddResources ()
	Add resources to a library or executable. More...

	usFunctionEmbedResources ()
	Embed resources in a library or executable. More...

	usFunctionGenerateModuleInit (src_var)
	Generate a source file which handles proper initialization of a module. More...

	usFunctionGetResourceSource ()
	Get a source file name for handling resource dependencies. More...

Detailed Description

This category includes CMake utility functions for external projects.

External projects can include the CMake scripts provided by the CppMicroServices library to automatically generate module initialization code and to embed external resources into a modules shared library.

Function Documentation

usFunctionAddResources ( )

Add resources to a library or executable.

This CMake function uses an external command line program to generate a ZIP archive containing data from external resources such as text files or images or other ZIP archives. The created archive file can be appended or linked into the target file using the usFunctionEmbedResources macro.

Each module can call this function to add resources and make them available at runtime through the Module class. Multiple calls to this function append the input files.

In the case of linking static modules which contain resources to the target module, adding the static module target name to the ZIP_ARCHIVES list will merge its resources into the target module.

Example usage:

set(module_srcs )
usFunctionAddResources(TARGET mylib
                       MODULE_NAME org_me_mylib
                       FILES config.properties logo.png
                      )

Parameters

TARGET	(required) The target to which the resource files are added.
MODULE_NAME	(required/optional) The module name of the target, as specified in the `US_MODULE_NAME` pre-processor definition of that target. This parameter is optional if a target property with the name US_MODULE_NAME exists, containing the required module name.
COMPRESSION_LEVEL	(optional) The zip compression level (0-9). Defaults to the default zip level. Level 0 disables compression.
WORKING_DIRECTORY	(optional) The root path for all resource files listed after the FILES argument. If no or a relative path is given, it is considered relative to the current CMake source directory.
FILES	(optional) A list of resource files (paths to external files in the file system) relative to the current working directory.
ZIP_ARCHIVES	(optional) A list of zip archives (relative to the current working directory or absolute file paths) whose contents is merged into the target module. If a list entry is a valid target name and that target is a static library, its absolute file path is used instead.

See also: usFunctionEmbedResources; The Resources System

usFunctionEmbedResources ( )

Embed resources in a library or executable.

This CMake function uses an external command line program to generate a ZIP archive containing data from external resources such as text files or images or other ZIP archives. The created archive file is appended or embedded as a binary blob to the target file.

Note: To set-up correct file dependencies from your module target to your resource files, you have to add a special source file to the source list of the target. The source file name can be retrieved by using usFunctionGetResourceSource. This ensures that changed resource files will automatically be re-added to the module.

There are two differend modes for including resources: APPEND and LINK. In APPEND mode, the generated zip file is appended at the end of the target file. In LINK mode, the zip file is compiled / linked into the target using platform specific techniques. LINK mode is necessary if certain tools make additional assumptions about the object layout of the target file (e.g. codesign on MacOS). LINK mode may result in slower module initialization and bigger object files. The default mode is LINK mode on MacOS and APPEND mode on all other platforms.

Example usage:

set(module_srcs )
usFunctionEmbedResources(TARGET mylib
                       MODULE_NAME org_me_mylib
                       FILES config.properties logo.png
                      )

Parameters

TARGET	(required) The target to which the resource files are added.
MODULE_NAME	(required/optional) The module name of the target, as specified in the `US_MODULE_NAME` pre-processor definition of that target. This parameter is optional if a target property with the name US_MODULE_NAME exists, containing the required module name.
APPEND	Append the resources zip file to the target file.
LINK	Link (embed) the resources zip file if possible.

For the WORKING_DIRECTORY, COMPRESSION_LEVEL, FILES, ZIP_ARCHIVES parameters see the documentation of the usFunctionAddResources macro which is called with these parameters if set.

See also: usFunctionAddResources; usFunctionGetResourceSource; The Resources System

usFunctionGenerateModuleInit ( src_var )

Generate a source file which handles proper initialization of a module.

This CMake function will store the path to a generated source file in the src_var variable, which should be compiled into a module. The modules source code must be compiled with the US_MODULE_NAME pre-processor definition. Example usage:

set(module_srcs )
usFunctionGenerateModuleInit(module_srcs)
add_library(mylib ${module_srcs})
set_property(TARGET ${mylib} APPEND PROPERTY COMPILE_DEFINITIONS US_MODULE_NAME=MyModule)

Parameters

src_var (required) The name of a list variable to which the path of the generated source file will be appended.

See also: Auto Loading Modules

usFunctionGetResourceSource ( )

Get a source file name for handling resource dependencies.

This CMake function retrieves the name of a generated file which has to be added to a modules source file list to set-up resource file dependencies. This ensures that changed resource files will automatically be re-added to the module.

Example usage:

set(module_srcs mylib.cpp)
usFunctionGetResourceSource(TARGET mylib
                            OUT module_srcs
                           )
add_library(mylib ${module_srcs})

Parameters

TARGET	(required) The name of the target to which the resource files are added.
OUT	(required) A list variable to which the file name will be appended.
LINK	(optional) Generate a suitable source file for LINK mode.
APPEND	(optional) Generate a suitable source file for APPEND mode.

See also: usFunctionAddResources; usFunctionEmbedResources

CppMicroServices

Functions

Detailed Description

Function Documentation