CMake Support

CMake support for external projects.

External projects can include the CMake scripts provided by the CppMicroServices library to automatically generate bundle initialization code, import static bundles, and to embed external resources into bundles.

usFunctionAddResources

usFunctionAddResources

Add resources to a library or executable.

usFunctionAddResources(TARGET target [BUNDLE_NAME bundle_name]
  [WORKING_DIRECTORY dir] [COMPRESSION_LEVEL level]
  [FILES res1...] [ZIP_ARCHIVES archive1...])

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() function.

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

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

Example
set(bundle_srcs )
usFunctionAddResources(TARGET mylib
                       BUNDLE_NAME org_me_mylib
                       FILES config.properties logo.png
                      )
One-value keywords
  • TARGET (required): The target to which the resource files are added.
  • BUNDLE_NAME (required/optional): The bundle name of the target, as specified in the c US_BUNDLE_NAME pre-processor definition of that target. This parameter is optional if a target property with the name US_BUNDLE_NAME exists, containing the required bundle 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.
Multi-value keywords
  • 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 bundle. If a list entry is a valid target name and that target is a static library, its absolute file path is used instead.

usFunctionEmbedResources

usFunctionEmbedResources

Embed resources in a library or executable.

usFunctionEmbedResources(TARGET target [BUNDLE_NAME bundle_name] [APPEND | LINK]
  [WORKING_DIRECTORY dir] [COMPRESSION_LEVEL level]
  [FILES res1...] [ZIP_ARCHIVES archive1...])

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. External resources can be added to a bundle using the usFunctionAddResources() function or directly using this function using similar parameters. 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 bundle 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 bundle.

There are two different 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 bundle initialization and bigger object files. The default mode is LINK mode on MacOS and APPEND mode on all other platforms.

Example
usFunctionEmbedResources(TARGET mylib
                         BUNDLE_NAME org_me_mylib
                         FILES config.properties logo.png
                        )
One-value keywords
  • TARGET (required): The target to which the resource files are added.
  • BUNDLE_NAME (required/optional): The bundle name of the target, as specified in the US_BUNDLE_NAME pre-processor definition of that target. This parameter is optional if a target property with the name US_BUNDLE_NAME exists, containing the required bundle name.
Options
  • 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.

usFunctionGetResourceSource

usFunctionGetResourceSource

Get a source file name for handling resource dependencies

usFunctionGetResourceSource(TARGET target OUT <out_var> [LINK | APPEND])

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

Example
set(bundle_srcs mylib.cpp)
usFunctionGetResourceSource(TARGET mylib
                            OUT bundle_srcs
                           )
add_library(mylib ${bundle_srcs})
One-value keywords
  • 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.
Options
  • LINK (optional): Generate a suitable source file for LINK mode.
  • APPEND (optional): Generate a suitable source file for APPEND mode.

usFunctionGenerateBundleInit

usFunctionGenerateBundleInit

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

usFunctionGenerateBundleInit(TARGET target OUT <out_var>)

This CMake function will append the path to a generated source file to the out_var variable, which should be compiled into a bundle. The bundles source code must be compiled with the US_BUNDLE_NAME pre-processor definition.

Example
set(bundle_srcs )
usFunctionGenerateBundleInit(TARGET mylib OUT bundle_srcs)
add_library(mylib ${bundle_srcs})
set_property(TARGET ${mylib} APPEND PROPERTY COMPILE_DEFINITIONS US_BUNDLE_NAME=MyBundle)
One-value keywords
  • TARGET (required): The name of the target for which the source file is generated.
  • OUT (required): A list variable to which the path of the generated source file will be appended.