Building Custom Modules#

Motivation#

It is recommended that third party modules be created within directories external to the xmera project tree. This allows one to replace the xmera project files completely separate from the third party module files.

Note

To learn how to write Xmera module, see the documentation at Xmera Modules.

Usage#

Module directory roots are controlled by the cmake parameter XMERA_MODULE_ROOTS. This parameter is a semicolon-separated list of directory paths that define the roots containing modules to add to the build. The default value to this parameter is a list containing all of the xmera core module roots e.g "${sourceDir}/fswAlgorithms/;${sourceDir}/simulation/;${sourceDir}/moduleTemplates/".

To add third party module roots one should duplicate this parameter in a custom CMakeUserPReset.json and append module root directories to the list E.g. "${sourceDir}/fswAlgorithms/;${sourceDir}/simulation/;${sourceDir}/moduleTemplates/;${sourceDir}/myModules/". The module root must also be symlinked into the xmera src directory.

cd src
ln -s </your/path/to/module/root> .

There is no limit to the number of external directories (module roots) one can add to the build.

To enable the compilation of third-party modules the module or group must be added to the XMERA_ENABLE_GROUPS Cmake parameter as shown on cmake.

cmake --preset base -DEXTERNAL_MODULES_PATH="<path-to-external-module-directory>"

Both absolute or relative paths to the external module folder are acceptable. Let the sample folder with custom Xmera code be called ExternalModules for the sake of this documentation. Further, assume it is located next to the Xmera source directory. From the Xmera source directory the command line build argument would be:

cmake --preset full -DXMERA_MODULE_ROOTS="${sourceDir}/fswAlgorithms/;${sourceDir}/simulation/; \
        ${sourceDir}/moduleTemplates/;${sourceDir}/myModules/"

Passing the external module’s path as above (Xcode, MS Visual Studio or makefile) allows CMake to create build rules that integrate the external modules as targets along side the Xmera components build. An IDE shows these under a folder with the same name as the build group.

Directory Structure#

The external module inclusion follows a strict directory structure resembling the existing Xmera repository. A single folder contains all the custom Xmera modules and message definitions in a specific sub-folder structure shown below.

custom-modules
├── CMakelists.txt
├── moduleA
│   ├── tests
│   │   └── test_moduleA.py
│   ├── CMakelists.txt
│   ├── moduleA.cpp
│   ├── moduleA.h
│   ├── moduleA.i
│   └── moduleA.rst
├── moduleB
│   ├── tests
│   │   └── test_moduleB.py
│   ├── CMakelists.txt
│   ├── moduleB.cpp
│   ├── moduleB.h
│   ├── moduleB.i
│   └── moduleB.rst
└── msgPayloadDef
    ├── CMakelists.txt
    ├── msgDefinitionA.h
    └── msgDefinitionB.h

custom-modules: This is the parent folder that holds all the custom Xmera modules, support files and messages.
Note that this folder can have any name, custom-modules is just a sample name here.

Frequently Asked Questions#

Can I store my custom Xmera folder on another drive?

On Linux and macOS, yes.
On Window this must be on the same drive as the Xmera source

How flexible are the folder names?

While the primary folder, called ExternalModules above, can assume any name, the key sub-folders must follow the exact naming shown above. If you change this you must write your own cmake file.

How do I import these custom modules when I write a Xmera python simulation script?

The custom Xmera modules are built into a Xmera.ExternalModules package. For example, to load a module called customCppModule, use:
```
from Xmera.ExternalModules import customCppModule
```