 |
Radium Engine
1.5.14
|
|
Radium Engine
1.5.14
|
As Radium relies on the CMake build and configuration system, this documentation focuses on how to configure your build system to use and extend Radium using Radium cmake utilities.
Complete functional examples using these cmake scripts are accessible in the src/tests/ExampleApps and src/tests/ExamplePluginWithLib directories of the Radium source distribution.
Once installed, either from source or from pre-built binaries, Radium could be used and extended in any application, library or plugin as a cmake package.
To integrate the Radium libraries into your build-chain configuration, you have to ask cmake to find the Radium package. As for any cmake package, this could be done by adding the following line into your CMakeLists.txt file:
This will bring only Radium Core component. See below how to select the components you need.
Remember to configure your project by giving the cmake command line option -DRadium_DIR=/path/to/installed/Radium/lib/cmake/Radium or -DCMAKE_PREFIX_PATH=/path/to/installed/Radium/lib/cmake so that the find_package command could find the Radium package definition. Once found, the Radium package defines a cmake target for each found components in the cmake namespace Radium.
When configuring your own target in your CMakeLists.txt file, you just need to link with those targets to get access to all the public interface of Radium (include search path, libraries, ...), for instance:
If your application needs another component than Core, you should select which ones you want with
The Radium components are :
IO : search only for the availability of the target Radium::IO and its dependency
On this target, you might also ask for support of several file loaders using the following properties defined on the target Radium::IO
The Radium package also defines several cmake functions, described below, that you can use to ease the configuration of your application, library or plugin, mainly to install them in a relocatable way while allowing their use from their own build-tree.
The functions defined by the Radium package are the following:
This function configures the executable target <NAME> for installation so that the installation directory is relocatable and distributable.
This function takes the following parameters:
| Parameter name | Parameter description |
|---|---|
<NAME> applicationName | The name of the executable target to configure and install |
<USE_PLUGINS> | If this option is given, the plugins installed into the Radium bundle at |
the installation time will be copied into the application bundle. <RESOURCES> ResourceDir1 ResourceDir2 ... | Optional list of directories to be considered as application resources and installed into the application bundle.
When installed into a directory <prefix>, the application bundle has the following structure on linux, windows or on MacOsX (if the executable is not configured as a MACOSX_BUNDLE):
For MACOSX_BUNDLE applications, a standard .app MacOsX application is generated (See https://developer.apple.com/.../BundleTypes/BundleTypes.html for bundle structure documentation).
For now (Radium version of May 2021):
To get relocatable packages, download pre-built binaries here: https://github.com/STORM-IRIT/Radium-Releases/releases
This cmake function configures the <TARGET> for installation and for further import in client project using find_package(<TARGET>). In order to use the library either through an imported target from an installed binary or as a project target in another component on the same build tree, this function defines an alias target with the same name as the imported one. This function also defines the symbol <TARGET>_EXPORTS so that, it could be used to allow symbol import/export from dynamic library.
This function takes the following parameters:
| Parameter name | Parameter description |
|---|---|
<TARGET> | The name of the target to configure |
<FILES> | Expected to be public headers, they will be installed in the include directory of the project installation configuration ${CMAKE_INSTALL_PREFIX}/include. |
<TARGET_DIR> | Optional. <FILES> will be installed into the ${CMAKE_INSTALL_PREFIX}/include/<TARGET_DIR> directory. If not, the files will be installed into ${CMAKE_INSTALL_PREFIX}/include/<TARGET> directory. |
<COMPONENT> | Optional. This option indicates that the library is to be configured as a component of an englobing multi-component package. |
<NAMESPACE> | If given, the imported target will be <NAMESPACE>::<TARGET>. If not, the imported target will be Radium::<TARGET> |
<PACKAGE_CONFIG> | If given, a configure script, to be used by find_package, will be generated. If not, only the exported targets will be generated. |
<PACKAGE_VERSION> | If given when the <PACKAGE_CONFIG> option also given, a cmake version file, used by find_package, will be generated. |
<PACKAGE_DIR> | If given, the cmake configuration script <TARGET>Config.cmake searched by find_package(<TARGET>) will be installed in the directory ${CMAKE_INSTALL_PREFIX}/<PACKAGE_DIR>. If not, the configure script will be installed in the directory <${CMAKE_INSTALL_PREFIX}/lib/cmake/Radium. |
Note that the parameters <PACKAGE_CONFIG> and <PACKAGE_DIR> could be omitted as the associated cmake package module could be generated using the function `configure_radium_package` documented below. If these parameters are given here, they will be forwarded to this function.
In order to allow usage of installed library in all supported systems (Linux, macOS, Windows), one of the public header, that might be named, e.g. <TARGET>Macros.hpp and included all the public or private headers, should contain the following :
Then, in the library source code, each exported symbol should be prefixed by <TARGET>_API e.g.
Assuming a library MyLib was configured as follows:
This library could be used either from its installed binaries :
or from the same build tree :
The <COMPONENT> option allows configuring and installing the library as a cmake component of a more general package (e.g. a component of the package PackageName). In this case, the imported target from the library will be available only if the client search for the meta-package using find_package(PackageName COMPONENTS <TARGET>).
A fully functional example on how to configure a library as a component of a more general package is given by Radium source code itself. The libraries Core, Engine, IO, Gui, and PluginBase are configured as components of the meta-package Radium.
When a Radium based component needs to access several resources to implement its functionalities, this function installs the required resources.
This function takes the following parameters:
| Parameter name | Parameter description |
|---|---|
<TARGET> targetName | The name of the target to configure. |
<RESOURCES_DIR> resourceDirectory | The directory in the source tree that contains the resource to install. |
<RESOURCES_INSTALL_DIR> baseDirectory | If given, the resources will be installed into the directory <install_prefix>/Resources/<RESOURCES_INSTALL_DIR>/. If not, the resources will be installed into the directory <install_prefix>/Resources/ where <install_prefix> is the installation directory of the target or the current binary dir of the build tree. |
<FILES> file1 file2 ... | If given, this allow to install only the given files from <DIRECTORY>. If not, all the files from <DIRECTORY> will be installed. |
For a Radium-based software component, resources can be of several types:
To access resources, the component might rely on a Ra::Core::Resources::ResourcesLocator object. Such an object allows accessing files located in some predefined directories:
<prefix>/Resources/Radium where <prefix> is the Radium installation directory.In order to allow client component to access its own resources, and to allow that either on the build-tree or once the component is installed without having to recompile or modify anything, this function both links (on supported systems, copy elsewhere) and installs the component resources at the given places.
As the process must be system and component independent it is the responsibility of the client package to configure the proper paths for resources management.
According to the installation layout of the Radium lib, that matches the GNU standard, but also to the macOS bundle architecture, Resources might be localized relatively to any binary object (library, executable, plugin, ...) The Radium installation hierarchy, that embeds base libraries, their resources and some executable files is the following:
In this hierarchy, Resources are located in the relative path ../Resources/ from any binary (executable or lib). The source code structure of the Radium libraries allows to have the same property on the build tree. When a Radium component needs to access some resources, it could either use the Ra::Core::Resources::ResourcesLocator::getRadiumResourcesDir() method or search for the resource relatively to a symbol defined in the component.
To do this, the source code (.cpp file) of the component could contain the following.
When using the `install_target_resources` function to configure the component resources' installation, the following call should be made to allow access from both the build-tree, and the install-tree using the above snippet.
This cmake function configures the package packageName for installation and for further import in client project using find_package(<TARGET>).
This function takes the following parameters:
| Parameter name | Parameter description |
|---|---|
<NAME> packageName | The name of the package to configure and install |
<PACKAGE_CONFIG> configFile.in | The configure script to be used by find_package. |
<PACKAGE_VERSION> major.minor.patch | If given, the version of the installed package |
<PACKAGE_DIR> packageDirName | If given, the cmake configuration script <TARGET>Config.cmake searched by find_package(<TARGET>) will be installed in the directory ${CMAKE_INSTALL_PREFIX}/<PACKAGE_DIR>. If not, the configure script will be installed in the directory <${CMAKE_INSTALL_PREFIX}/lib/cmake/Radium. |
<NAME_PREFIX> packagePrefix | If given, prefix added to the name of the installed config script <packagePrefix><packageName>Config.cmake. |
This function is called implicitly, when defining a single component package, when the parameters <PACKAGE_CONFIG> and <PACKAGE_DIR>, with optional <PACKAGE_VERSION>, are given to the library configuration function `configure_radium_library`.
This function also allows defining multi-component packages for selective import using the find_package(packageName [COMPONENTS comp1 comp2 ...] command when called explicitly with an appropriate PACKAGE_CONFIG parameter. In this case, the parameter <NAME_PREFIX> will allow to add multi-component package name as a prefix of the component config script.
If the optional <PACKAGE_VERSION> parameter is given, a cmake version file is generated, using the SameMajorVersion compatibility policy, that exports the cmake variables <NAME>_VERSION , <NAME>_VERSION_MAJOR, <NAME>_VERSION_MINOR and <NAME>_VERSION_PATCH.
This function, intended to be used in a Config.incmake script defines the resources access properties for the exported target <target>. Based on these properties, client application and libraries might access to the resources of an imported target found by FindPackage(PackageName)
This function takes the following parameters:
| Parameter name | Parameter description |
|---|---|
<TARGET> target | The name of the package to configure and install |
<ACCESS_FROM_PACKAGE> path | The path from the installed package module to the installed resources directory. |
<PREFIX> resourcesPrefix | Name of the directory in which the resources are installed. |
As described above, the installation tree of any installed target, if configured with radium cmake utilities, looks like the following
where target is the name of the exported target, targetConfig.cmake the cmake package module installed when installing the target and resourcesPrefix the resource prefix defined when installing the resources for the target (can be empty).
In the above example, the <ACCESS_FROM_PACKAGE> path parameter of the function `radium_exported_resources` should be set to "../.." This parameter must contain the relative path that start from the package module installation directory, here <prefix>/lib/cmake, to the resources' installation directory, here <prefix>/Resources.
This cmake function configures the target NAME pluginName to be compiled, linked and optionally installed as a Radium Plugin. The plugin and its optional resources might then be used in any plugin-compatible Radium application. If the plugin is installed in the Radium distribution bundle, it will be embedded in all bundled application installed later.
This function takes the following parameters:
| Parameter name | Parameter description |
|---|---|
NAME pluginName | Name of the target to be linked and installed as a plugin |
[RESOURCES ResourceDir1 [ResourceDir2 ...] | Optional. List of directories, in the source tree, containing the plugin own resources. |
[HELPER_LIBS helperlib1 [helperlib2 ...]] | List of libraries the plugin depends on. |
[INSTALL_IN_RADIUM_BUNDLE] | Optional. If given, the plugin is installed in the Radium general bundle (${RADIUM_ROOT_DIR}/Plugins) instead of being installed in the ${CMAKE_INSTALL_PREFIX} |
The pluginName target must be a dynamic library that exports a class inheriting from QObject and Ra::Plugins::RadiumPluginInterface. The optional resources associated with the plugin are own resources that the plugin needs to be functional and will be installed as described below. The optional helper libraries can be local targets, configured in the same build tree, or imported targets, resulting from a find_package(...). If a helper library need to access its own resources, it must be configured using `configure_radium_library` if it is a local target or imported from an installed target configured the same way.
The directory hierarchy in which a plugin will be installed (or where the build target will be) is the following:
where <prefix> refer to the base plugin dir into the build tree or the installation directory.
<prefix> refers to the directory ${CMAKE_CURRENT_BINARY_DIR}/Plugins. Resources directories are linked into Resources directory on system that supports links, copied otherwise. Helper libs are not copied into the hierarchy.<prefix> refers to ${RADIUM_ROOT_DIR}/Plugins. Optional resources directories are copied into Resources directory.<prefix> refers to ${CMAKE_INSTALL_PREFIX}. Optional resources directories are copied into Resources directory.When a plugin is installed and depends on a helper library that embed its own resources, the helper resources are copied into the <prefix>/Resources directory so that the helper lib could find its resources as described in the section `install_target_resources`. In this hierarchy, a plugin will access to its resources in a way very similar than any other library. Only one level of hierarchy, whose name is the plugin name, will be added.
The Radium distribution is based on several cmake package components. A component defines a set of imported targets, as well as properties on these targets (e.g. headers, resources, ...) and manage all the dependencies of these targets (dependencies over other components or on external packages).
To create a new Radium component named NewComponent (e.g. a new library one can add to a project with find_package(Radium COMPONENT NewComponent)), you have to do the following steps :
NewComponent in the <Radium_source_dir>/src with component's source and header filesCMakeLists.txt as described in the Configuring client and extension libraries.CMakeLists.txt configuration script, configure the main target library by using the COMPONENT option of the function configure_radium_library and add this target to the RADIUM_COMPONENT variable :where ${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in contains the configuration of the installed component as described below.
<Radium_source_dir>/src/CMakeLists.txt to add the subdirectory that contains the component source codeHence, Radium compilation and install include NewComponent.
During Radium install, cmake generates a configuration file for the component, from Config.cmake.in file located in the source directory of the component. The generation setup is done by configure_radium_library. This file provides components informations needed by find_package(Radium COMPONENT NewComponent)
Here is a simple example of Config.cmake.in for the NewComponent example.
You can refer to the configuration of the Core, Engine, Gui, PluginBase and IOcomponents for more practical and complete examples.
When writing your cmake configuration script CMakeLists.txt, you might rely on the following guideline to configure the project ProjectName. Note that these are only guidelines and that you can always write your cmake script from scratch, assuming you understand what you do.
Then, according to the type of the targets defined in your project (application, single library, set of libraries, plugin, mix of them), you might configure your project according to the following guidelines.
Configuring an installable and relocatable application is very easy with Radium cmake scripts. First, an executable target that depends on Radium libraries (internal Radium libraries or client libraries) should be configured with a cmake script such as
Then, the application is configured to be relocatable after installation with
Once compiled and installed, the directory <${CMAKE_INSTALL_PREFIX}>, set to installed-<COMPILER_ID>-<CONFIGURATION> into the root of the build tree if not specified at configure time, is a relocatable directory that contains the bundled application and associated resources.
Note that, on MacOsX, if the executable target is configured using the MACOSX_BUNDLE option, only the bin directory is created into this bundle, and it contains the relocatable .app bundle. If the option MACOSX_BUNDLE is not given, the executable will not be a bundled macOS .app but a command line application and will be installed as any application on Linux.
The resources associated to an application are installed using the `install_target_resources`.
An installable library could be used to add functionalities built over the Radium libraries and to make these functionalities available to developers. Once installed, a library consists in:
.so, .dylib or .dll)find_packageIn order to fulfill Radium conventions, a library will be identified by a name into a namespace.
To configure an installable library based on Radium, it is recommended to have the following CMakeLists.txt
The Config.cmake.in file used to configure the package could be written similarly to what described into the following section but with only one component.
When configuring a library, a cmake package configuration file should be written so that the cmake package configuration module is installed alongside the library. Meanwhile, when several libraries must be used as components in a single package (e.g. the Radium internal libraries are all gathered into the single Radium package), a more general configuration module has to be defined.
For this, instead of defining a configuration package for each configured library, the parameter PACKAGE_CONFIG of the function `configure_radium_library` should be omitted and the function `configure_radium_package` should be used.
Standard usage of this function requires to have some libraries configured like the following:
Once this is done, the package should be configured using
Where the configuration file <packageName>Config.cmake.in should be written as the example below. (see cmake documentation for deeper explanations on how to write a package configuration file).
Based on the above example, once the package <packageName> is found, the targets <namespace>::<firstLib> and <namespace>::<secondLib> will be imported in the current project and should be used as any imported Radium targets.
When a library need to access resources, the `install_target_resources` must be called once the library target is configured as explain above. This result, as an example, in the following cmake snippet if the library ${NAME_OF_LIBRARY} need to access glsl source file from the resource directory ${CMAKE_CURRENT_SOURCE_DIR}/Shaders in the source tree.
In this case, the library must also associate its resources with its exported target so that, when the library is imported in an application, plugin or other library, the resources will be made available. For doing this, the corresponding package configuration file (e.g. <packageName>Config.cmake.in) should add properties to all exported targets describing their resources. The following properties should be added to the corresponding targets:
RADIUM_TARGET_RESOURCES_PREFIX defines the directory prefix to access the library resourcesRADIUM_TARGET_INSTALLED_RESOURCES specifies where are installed the resources on the system.These properties, located in the installation tree, are the same as those defined when installing resources for a library and should be set by using the function `radium_exported_resources` in the <packageName>Config.cmake.in such as
where <resourcesPrefix> corresponds to the parameter PREFIX used when installing the resources for the target <namespace>::<libtarget>.
1.9.8