Using CMake¶

To build a package¶

To build a Sen package, use the add_sen_package function:

add_sen_package(
  TARGET <name>
  [MAINTAINER <name>]
  [DESCRIPTION <text>]
  [VERSION <version>]
  [BASE_PATH <path>]
  [EXPORT_NAME <name>]
  [SCHEMA_PATH <path>]
  [GEN_HDR_FILES <variable>]
  [CODEGEN_SETTINGS <file>]
  [HLA_OUTPUT_DIR <path>]
  [SOURCES <files...>]
  [DEPS <targets...>]
  [PRIVATE_DEPS <targets...>]
  [STL_FILES <files...>]
  [HLA_FOM_DIRS <dirs...>]
  [HLA_MAPPINGS_FILE <files...>]
  [EXPORTED_CLASSES <names...>]
  [EXPORT_INTERFACES]
  [IS_COMPONENT]
  [NO_SCHEMA]
  [PUBLIC_SYMBOLS]
  [TEST_TARGET <name>]
)

It takes the following parameters:

For example,

add_sen_package(
  TARGET calculators
  MAINTAINER "Enrique Parodi Spalazzi (enrique.parodi@airbus.com)"
  VERSION "0.0.1"
  DESCRIPTION "Example package"
  SOURCES src/casio_calculator.cpp src/faulty_calculator.cpp src/client.cpp
  STL_FILES stl/calculator.stl
  SCHEMA_PATH ${CMAKE_CURRENT_BINARY_DIR}
)

add_sen_package builds and registers the package; it writes no install() rule. That is fine while the package is loaded from your build tree, which is what the shipped examples do. If you want to ship it, install it yourself: the shared library so Sen can load it, and, if anything is meant to compile against your package, the headers code generation produced. GEN_HDR_FILES gives you that list. Sen's own libraries do the same thing by hand, which is why each of them carries its own install rules for the headers it exports. Creating your own Conan package walks through it with a worked example.

How to use the DEPS and PRIVATE_DEPS options for dependencies¶

The DEPS and PRIVATE_DEPS options of the add_sen_package function are used to link dependencies to a package. These dependencies can be of two different types:

• Other Sen packages: these dependencies are linked against your package and their BASE_PATH properties are transmitted to your package, so you can include STL/XML files in the generated code of your package. This is very important, as only linking Sen packages is not enough for using their interface files, you need to add them to the DEPS option.
• Dependencies that are not Sen packages: These are just linked to your Sen package as dependencies. DEPS links the dependency as PUBLIC and PRIVATE_DEPS does it as PRIVATE.

Using Sen packages as dependencies of other Sen packages¶

If you plan to use the package as a dependency for other packages, and therefore want the symbols in that package to be exported, set the PUBLIC_SYMBOLS flag in the add_sen_package function. This can also be achieved by calling sen_generate_package, which is an alias of add_sen_package with the PUBLIC_SYMBOLS flag on. However, the use of sen_generate_package is not advised as it will be deprecated in the future, and it was only added to keep retro-compatibility with previous versions.

Important note: only types in the generated code are exported, if you want any of the types of your package implementation (the ones defined in the SOURCES) to be exported, you need to explicitly export it using the SEN_EXPORT macro, as the symbols in the package will be hidden by default.

Below is an example of two packages, where one of them is linked as a dependency to the other:

add_sen_package(
  TARGET hla_fom
  BASE_PATH ${CMAKE_CURRENT_LIST_DIR}
  HLA_OUTPUT_DIR hla_fom
  HLA_FOM_DIRS rpr netn link16
  GEN_HDR_FILES fom_headers
  HLA_MAPPINGS_FILE base_mappings.xml
  SCHEMA_PATH ${CMAKE_CURRENT_BINARY_DIR}
  PUBLIC_SYMBOLS
)

add_sen_package(
  TARGET aircrafts
  MAINTAINER "Enrique Parodi Spalazzi (enrique.parodi@airbus.com)"
  VERSION "0.0.1"
  DESCRIPTION "Dummy entities for testing"
  STL_FILES stl/dummy_aircraft.stl
  SOURCES src/dummy_aircraft_impl.cpp
  DEPS hla_fom sen::util
  SCHEMA_PATH ${CMAKE_CURRENT_BINARY_DIR}
)

As you can see, the hla_fom package is linked as a dependency of the aircrafts package, therefore it is marked with the PUBLIC_SYMBOLS flag.

How to test the internal implementation of a package? The TEST_TARGET option¶

Sen packages have all symbols hidden by default. This means that if you want a test executable for the implementation details of a package, you cannot link that executable directly against the package and expect it to work. All the symbols in the package will not be visible to the test executable.

In order to tackle this problem, we created the TEST_TARGET option on the add_sen_package function. In the TEST_TARGET option, the user can specify the name of a test target (e.g. <target_name>_test) which will finally be a STATIC library containing the package code.

Then, the test executable can be linked against that test target and, due to the static linking, all the symbols will be available in your executable.

However, adding the TEST_TARGET option changes how the add_sen_package function works: in order to avoid compiling the package twice (one as <target_name> and one as <target_name>_test), Sen uses an intermediate cmake OBJECT target called <target_name>_obj, which is the one that is actually compiled. This implies that any modification you want to make to your package outside the add_sen_package function has to be applied to <target_name>_obj and not to <target_name>.

Below is an example of a Sen package with the TEST_TARGET option enabled:

add_sen_package(
  TARGET
    my_package
  SOURCES
    ${base_sources}
  STL_FILES
    stl/configuration.stl stl/options.stl stl/types.stl
  DEPS
    asio::asio
    llhttp::llhttp
    nlohmann_json::nlohmann_json
    spdlog::spdlog
  BASE_PATH
    ${CMAKE_CURRENT_SOURCE_DIR}
  TEST_TARGET
    my_package_test
)

target_include_directories(my_package_obj PUBLIC directories/to/include)

add_executable(gtest_for_my_package test.cpp)

target_link_libraries(gtest_for_my_package PRIVATE my_package_test)

As you can see in the example above, the include directories property is set to my_package_obj and not to my_package or my_package_test. Afterward, the gtest_for_my_package executable is linked against the my_package_test.

How to implement a custom Sen component, the IS_COMPONENT flag (Advanced)¶

If you want to implement your own Sen component, just add the IS_COMPONENT flag to the add_sen_package function. Below is a usage example of the add_sen_package function being used to add a Sen component:

add_sen_package(
        TARGET
          example_component
        MAINTAINER
          "Your Name (your.name@example.com)"
        VERSION
          "0.0.1"
        DESCRIPTION
          "A component built as part of this project"
        SOURCES
          component.cpp
        STL_FILES
          stl/example.stl
        IS_COMPONENT
)

Other utilities¶

Direct code generation¶

sen_generate_cpp generates C++ code from STL or HLA FOM files and adds the result to an existing CMake target. For the common case of building a full Sen package, prefer add_sen_package() instead.

sen_generate_cpp(
    TARGET <name>
    [OUTPUT_DIR <path>]
    [BASE_PATH <path>]
    [CODEGEN_SETTINGS <file>]
    [GEN_HDR_FILES <variable>]
    [SCHEMA_FILE <path>]
    [SCHEMA_COMPONENT_NAME <name>]
    [HLA_OUTPUT_DIR <path>]
    [STL_FILES <files...>]
    [HLA_FOM_DIRS <dirs...>]
    [HLA_MAPPINGS_FILE <files...>]
    [VISIBLE_CLASSES <YES|NO>]
)

For example,

sen_generate_cpp(
    TARGET
        terminal_lib
    STL_FILES
        stl/remote_shell.stl
)

or,

sen_generate_cpp(
    TARGET
        fom_lib
    HLA_FOM_DIRS
        rpr
        netn
    GEN_HDR_FILES
        fom_headers
    HLA_MAPPINGS_FILE
        mapping.xml
)

Static analysis¶

The sen_enable_static_analysis function enables clang-tidy for the target.

sen_enable_static_analysis(ether)

UML diagrams¶

Sen can generate PlantUML diagrams from STL or HLA FOM files.

sen_generate_uml(
    TARGET <name>
    OUT <file>
    [BASE_PATH <path>]
    [STL_FILES <files...>]
    [HLA_FOM_DIRS <dirs...>]
    [HLA_MAPPINGS_FILE <files...>]
    [CLASSES_ONLY | TYPES_ONLY | TYPES_ONLY_NO_ENUMS]
)

For example:

sen_generate_uml(
    TARGET
        fom_lib_uml
    OUT
        ${CMAKE_CURRENT_BINARY_DIR}/fom.plantuml
    HLA_FOM_DIRS
        rpr
        netn
    CLASSES_ONLY
)

HTML reference¶

Sen can generate a browsable HTML reference from STL or HLA FOM files. The output is a directory rather than a single file: index.html plus the assets beside it, which is why OUT names a directory here and a file in the functions above.

sen_generate_html(
    TARGET <name>
    OUT <dir>
    [TITLE <text>]
    [BASE_PATH <path>]
    [STL_FILES <files...>]
    [HLA_FOM_DIRS <dirs...>]
    [HLA_MAPPINGS_FILE <files...>]
)

For example:

sen_generate_html(
    TARGET
        fom_reference
    OUT
        ${CMAKE_CURRENT_BINARY_DIR}/reference
    TITLE
        "RPR and NETN"
    HLA_FOM_DIRS
        rpr
        netn
)

Target configuration¶

sen_configure_target(<target>) applies Sen's build settings to a target that already exists. It takes the target name and nothing else, and stops the configure step with a fatal error if the name is not a target.

add_sen_package() calls it for you. Call it directly for a target you created yourself, such as a plain executable or library that links against Sen.

Build information¶

sen_add_build_info(<target> <name>) generates one small source file carrying the commit the target was built from, and adds it to the target. <name> only names the generated file, so anything unique within the build directory works; the target name is the usual choice.

add_sen_package() calls it for you. Call it directly for a component you built with plain add_library. component.h declares getGitRef(), getGitHash(), getGitStatus() and getBuildTime() without defining them, and the generated file is what defines them, so without the call those four are undefined at link time. The linker names the mangled symbol, not the missing call, so the error does not point at this page.

add_library(my_component SHARED src/my_component.cpp)
sen_configure_target(my_component)
target_link_libraries(my_component PUBLIC sen::kernel)
sen_add_build_info(my_component my_component)

Python and YAML generation¶

You can use Python to store your configuration data. This provides a more flexible, readable and powerful way of managing complex parameters.

The Sen kernel takes the configuration data from YAML files, but Python can be used to generate the YAML files. To help you in this task, Sen provides means for generating Python code consisting in dataclasses for a type-safe approach.

There is a CMake function that helps you invoke the code generator:

sen_generate_python(
    TARGET <name>
    [OUTPUT_DIR <path>]
    [BASE_PATH <path>]
    [CODEGEN_SETTINGS <file>]
    [GEN_HDR_FILES <variable>]
    [SCHEMA_FILE <path>]
    [SCHEMA_COMPONENT_NAME <name>]
    [HLA_OUTPUT_DIR <path>]
    [STL_FILES <files...>]
    [HLA_FOM_DIRS <dirs...>]
    [HLA_MAPPINGS_FILE <files...>]
)

sen_generate_python and sen_generate_cpp are the same function with the output language fixed, so the arguments match one for one. The only exception is VISIBLE_CLASSES, which controls C++ symbol visibility and is ignored for Python.

There is one output .py file per input file, and the output folder structure mirrors the input. Each generated directory also gets an empty __init__.py, so the result imports as a package, and a py.typed marker, so type checkers use the annotations.

Once you have your generated Python code, you will want to write the configuration Python file(s). There is another CMake function that helps you in generating the final YAML file:

sen_generate_yaml(
    TARGET <name>
    SCRIPT <file>
    OUTPUT <file>
    [DEPS <targets...>]
)

In the DEPS argument you need to set all the dependencies, and be sure to add the target that you used to generate the Python code. This way, this function will automatically configure the PYTHONPATH with the folders that host the generated code.

If mypy is found, this function also creates a <TARGET>_check target that type-checks the script, and makes TARGET depend on it so type checking runs before YAML generation.

Keep in mind that the generated Python code and the generated YAML file are not meant to be kept under version control. The idea is to have a single source of truth: your config script for the data, and the STL (or HLA) files for the types.

Obtaining external interfaces information¶

Sen provides the necessary functionality to obtain interfaces files (such as stls or HLA FOM xmls) when consuming packages from outside your project.

The following CMake utility obtains interface-related properties from a target such as STL_FILES, BASE_PATH or HLA_FOM_DIRS.

get_external_interfaces(
    TARGET <targetName>
    INSTALLATION_DIR <directory>
)

After calling this function, you will be able to fetch the INSTALL_STL_FILES, INSTALL_BASE_PATH, INSTALL_HLA_FOM_DIRS and INSTALL_HLA_MAPPINGS properties, which contain the paths and information you need to generate code with the functions described above.

A more detailed guide on this function and on the whole process of exporting and consuming external interfaces can be found in the following guides:

• How to export interfaces in Sen-based projects
• How to consume external interfaces in Sen-based projects
• How to generate CMake packages to export pre-built interfaces

Automatic configuration and installation of -config.cmake.in files¶

A -config.cmake.in file contains the configuration of a CMake package. In a nutshell, this files contain the CMake code of a project that will be executed when you call find_package() to consume it externally. Sen offers a small CMake helper who eases the installation process of this type of files. This function will come in handy when a project contains several -config.cmake.in files in different subdirectories of the project.

The function takes a list of directories who contain -config.cmake.in files and configures the files so that they are generated and installed in your CMAKE_INSTALL_PREFIX directory. It will also install the -config.cmake.in files found in the current list directory. This directory will almost certainly match the directory where your install.cmake file is found, since this function should only be used when generating a CMake install package.

configure_exportable_packages(
    [INTERFACES_CONFIG_DIRS <directories...>]
    [TARGET_NAME_CMAKEDIRS]
)

The per-package layout that TARGET_NAME_CMAKEDIRS produces is where find_package() searches under a prefix, so a consumer pointing CMAKE_PREFIX_PATH at the prefix itself can resolve each package by name.

A package created with add_sen_package() links sen::kernel publicly, so that target has to exist before your own config file loads. Ask for it in your -config.cmake.in:

@PACKAGE_INIT@

include(CMakeFindDependencyMacro)
find_dependency(sen)

Without it a consumer of your package sees a CMake error naming sen::kernel, and it arrives while generating rather than from their find_package() call, which makes it read as a fault in their own project.

More detail on functionality and information on when should this function be used can be found on the How to generate CMake packages to export pre-built interfaces guide.