Skip to content

API

Note: auto-generated from comments in: ./API.cmake

API.cmake:

API of the fprime CMake system. These functions represent the external interface to all of the fprime CMake system. Users and developers should understand these functions in order to perform basic CMake setup while building as part of an fprime project.

The standard patterns include: - Add a directory to the fprime system. Use this in place of add_subdirectory to get cleanly organized builds. - Register an fprime module/executable/ut to receive the benefits of autocoding. - Register an fprime build target/build stage to allow custom build steps. (Experimental)

Macro skip_on_sub_build:

Skip this remaining code in the current function or file when executing in the context of a sub build. Sub builds execute utility and setup functions in fprime. However, certain CMake functions are not appropriate in this context and should be skipped.

Macro restrict_platforms:

Restricts a CMakeLists.txt file to a given list of supported platforms, toolchains, and features. This prevents usage on platforms/toolchains for which the module is incapable of being used and replaces the historical pattern of an if-tree detecting unsupported platforms in most circumstances.

Valid inputs include names of platforms (e.g. Linux), names of specific toolchains (e.g. aarch64-linux), and platform supported feature sets (e.g. SOCKETS, which inspects the FPRIME_HAS_SOCKETS flag).

Usage: restrict_platforms(Linux Darwin) # Restricts to Linux and Darwin platforms -or- restrict_platforms(Posix) # Restricts to posix systems -or- restrict_platforms(SOCKETS) # Restricts to platforms where FPRIME_HAS_SOCKETS is TRUE

Args: ARGN: list of platforms that are supported

Function add_fprime_subdirectory:

Adds a subdirectory to the build system. This allows the system to find new available modules, executables, and unit tests. Every module, used or not, by the deployment/root CMAKE file should be added as a subdirectory somewhere in the tree. CMake's dependency system will prevent superfluous building, and add_fprime_subdirectory calls construct the super-graph from which the build graph is realized. Thus it is inconsequential to add a subdirectory that will not be used, but all code should be found within this super-graph to be available to the build.

Every subdirectory added should declare a CMakeLists.txt. These in-turn may add their own sub- directories. This creates a directed acyclic graph of modules, one subgraph of which will be built for each executable/module/library defined in the system. The subgraph should also be a DAG.

This directory is computed based off the closest path in FPRIME_BUILD_LOCATIONS. It must be set to be used. Otherwise, an error will occur. EXCLUDE_FROM_ALL can also be supplied. See: https://cmake.org/cmake/help/latest/command/add_fprime_subdirectory.html

Note: Replaces CMake add_subdirectory call in order to automate the [binary_dir] argument. fprime subdirectories have specific binary roots to avoid collisions, and provide for the standard fprime #include paths rooted at the root of the repo.

Arguments: - FP_SOURCE_DIR: directory to add (same as add_directory) - EXCLUDE_FROM_ALL: (optional) exclude any targets from 'all'. See: https://cmake.org/cmake/help/latest/command/add_fprime_subdirectory.html

Function fprime_attach_custom_targets:

Attaches custom fprime targets (cmake/targets) and their associated autocoding to the supplied build target. This is done automatically by the register_fprime_* family of functions and provides deferred target setup for use with fprime_add_*_build_target family functions.

BUILD_TARGET_NAME: name of build target to attach targets and autocoding to

Function register_fprime_library:

Registers a library using the fprime build system. This comes with dependency management and fprime autocoding capabilities. The first argument is the name of this module and will become the build target name. Sources, autocoder inputs, link dependencies, and headers are each passed in after the directives SOURCES, AUTOCODER_INPUTS, DEPENDS, and HEADERS, respectively. Each directive may be used one time and dictates the contents of arguments until the next directive.

Example:

register_fprime_library(
        MyFprimeModule
    SOURCES
        source1.cpp
        source2.cpp
    AUTOCODER_INPUTS
        model.fpp
    DEPENDS
        -lm
    HEADERS
        module.h
)

Note

This delegates to CMake's add_library call. The library argument EXCLUDE_FROM_ALL is supported.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function register_fprime_module:

See register_fprime_library. This provides the same capability as register_fprime_library using the backwards-compatible name.

Note

Variables SOURCE_FILES, MOD_DEPS, etc. are still supported but are no longer recommended. Users are encouraged to update at their convenience.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function fprime_add_library_build_target:

Registers a library using the fprime build system without setting up autocoding or target support. See register_fprime_library.

Note

Users may set up custom target and autocoder support by calling fprime_attach_custom_targets.

This function sets "INTERNAL_MODULE_NAME" in PARENT_SCOPE to pass-back module name for target registration.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function register_fprime_executable:

Registers an executable using the fprime build system. This comes with dependency management and fprime autocoding capabilities. The call format is identical to register_fprime_library.

Example:

register_fprime_executable(
        MyFprimeExecutable
    SOURCES
        source1.cpp
        source2.cpp
    AUTOCODER_INPUTS
        model.fpp
    DEPENDS
        -lm
    HEADERS
        module.h
)

Note

This delegates to CMake's add_executable call. The argument EXCLUDE_FROM_ALL is supported.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function fprime_add_executable_build_target:

Registers a executable using the fprime build system without setting up autocoding or target support. See register_fprime_executable.

Note

Users may set up custom target and autocoder support by calling fprime_attach_custom_targets.

This function sets "INTERNAL_MODULE_NAME" in PARENT_SCOPE to pass-back module name for target registration.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function register_fprime_deployment:

Registers a deployment using the fprime build system. This comes with dependency management and fprime autocoding capabilities. The call format is identical to register_fprime_library. Deployments come with custom target and autocoding support that allows them to run "targets" across their dependency trees (i.e. run all unit tests for components used in this deployment).

Example:

register_fprime_deployment(
        MyFprimeDeployment
    SOURCES
        source1.cpp
        source2.cpp
    AUTOCODER_INPUTS
        model.fpp
    DEPENDS
        MyFprimeDeployment_Top
    HEADERS
        module.h
)

Note

This delegates to CMake's add_executable call. The argument EXCLUDE_FROM_ALL is supported.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function fprime_add_deployment_build_target:

Registers a deployment using the fprime build system without setting up autocoding or target support. See register_fprime_deployment.

Note

Users may set up custom target and autocoder support by calling fprime_attach_custom_targets.

This function sets "INTERNAL_MODULE_NAME" in PARENT_SCOPE to pass-back module name for target registration.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function register_fprime_config:

Registers a configuration build target using the fprime build system. This comes with dependency management and fprime autocoding capabilities. The call format is identical to register_fprime_library and additionally supports the CONFIGURATION_OVERRIDES directive. This allows users to override the configuration files supplied by previous configuration modules supplied by the build (e.g. fprime default configuration and library configuration). DEPENDS and EXCLUDE_FROM_ALL are not supported.

All configuration module sources (SOURCES, HEADERS, and AUTOCODER_INPUTS) are copied into the build cache. Overrides are copied into the original module's build that the file overrides as this preserves the original build module set up. Overrides only work in order of detection within the CMakeList.txt tree:

platform -> fprime config -> library -> project.

Warning

Specifying headers in this command is crucial to providing as configuration.

Note

Configuration is built as a series of STATIC libraries in order to allow for interdependencies between config and Fw_Types regardless of the Fw_Types library type.

Example: 

register_fprime_config(
        MyFprimeConfig
    SOURCES
        config.cpp
    AUTOCODER_INPUTS
        config.fpp
    HEADERS
        config.hpp
    CONFIGURATION_OVERRIDES
        FpConfig.fpp
        FpConfig.hpp

Function fprime_add_config_build_target:

Registers config using the fprime build system without setting up autocoding or target support. See register_fprime_config.

Note

Users may set up custom target and autocoder support by calling fprime_attach_custom_targets.

This function sets "INTERNAL_MODULE_NAME" in PARENT_SCOPE to pass-back module name for target registration.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function register_fprime_ut:

Registers a unit test using the fprime build system. This comes with dependency management and fprime autocoding capabilities. The call format is identical to register_fprime_library. Unit tests come with custom target and autocoding support.

This function only creates a target when unit test support is enabled on the build.

Example:

register_fprime_ut(
        MyUnitTest
    SOURCES
        source1.cpp
        source2.cpp
    AUTOCODER_INPUTS
        model.fpp
    DEPENDS
        MyFprimeModule
    HEADERS
        module.h
)

Note

This delegates to CMake's add_executable call. The argument EXCLUDE_FROM_ALL is supported.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Function fprime_add_unit_test_build_target:

Registers a unit test using the fprime build system without setting up autocoding or target support. See register_fprime_ut.

Note

Users may set up custom target and autocoder support by calling fprime_attach_custom_targets.

This function sets "INTERNAL_MODULE_NAME" in PARENT_SCOPE to pass-back module name for target registration.

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Macro register_fprime_target:

This function allows users to register custom build targets into the build system. These targets are defined in a CMake file and consist of three functions that operate on different parts of the build: global, per-module, and per-deployment. See: Targets.

This function takes in either a file path to a CMake file defining targets, or an short include path that accomplishes the same thing. Note: make sure the directory is on the CMake include path to use the second form. The supplied file should define three functions: add_global_target, add_module_target, and add_deployment_target.

TARGET_FILE_PATH: include path or file path file defining above functions

macro(register_fprime_target TARGET_FILE_PATH) if (CMAKE_DEBUG_OUTPUT) message(STATUS "[target] Registering custom target: ${TARGET_FILE_PATH}") endif() register_fprime_list_helper("${TARGET_FILE_PATH}" FPRIME_TARGET_LIST OFF) endmacro(register_fprime_target)

Macro register_fprime_list_helper:

Helper function to do the actual registration. Also used to side-load prescan to bypass the not-on-prescan check. Takes in a boolean argument TO_PREPEND to determine if the target should be prepended to the list.

Macro register_fprime_build_autocoder:

This function allows users to register custom autocoders into the build system. These autocoders will execute during the build process. An autocoder is defined in a CMake file and must do three things: 1. Call one of autocoder_setup_for_individual_sources() or autocoder_setup_for_multiple_sources() from file scope 2. Implement <autocoder name>_is_supported(AC_POSSIBLE_INPUT_FILE) returning true the autocoder processes given source 3. Implement <autocoder name>_setup_autocode AC_INPUT_FILE) to run the autocoder on files filter by item 2.

This function takes in either a file path to a CMake file defining an autocoder target, or an short include path that accomplishes the same thing. Note: make sure the directory is on the CMake include path to use the second form.

TARGET_FILE_PATH: include path or file path file defining above functions

Function create_implementation_interface:

Helper function to create implementation interface library once and only once to ensure it exists.

IMPLEMENTATION: implementation library name (resolved)

Function register_fprime_implementation:

Designates that the given implementor implements the required implementation and registers it as a library. This library will always be of type OBJECT to ensure that it will override at link time as expected. The call format is identical to register_fprime_library, but requires the IMPLEMENTS directive to indicate which implementation is being implemented.

Warning

The result of this call will always be an OBJECT library.

Example:

register_fprime_implementation(
        MyImplementation
    IMPLEMENTS
        SomeImplementationInterface
    SOURCES
        source1.cpp
        source2.cpp
    AUTOCODER_INPUTS
        model.fpp
    HEADERS
        module.h
)

MODULE_NAME: (optional) module name. Default: ${FPRIME_CURRENT_MODULE} ARGN: sources, autocoder inputs, etc preceded by a directive (i.e. SOURCES or DEPENDS)

Adds a named os implementation.

Assumptions: 1. NAMES is a list of 1 or more named files separated by ; 2. There exists a file named Default${FIRST_ITEM}, where FIRST_ITEM is the first element in NAME, in the same directory where this cmake function was called 3. For each item e listed in NAMES, there exists a file called ${e}.hpp and ${e}.cpp in the same directory where this cmake function was called

NAMES: list of named files to add to this module. The first will be treated as the name of the module. i.e. File;Directory;FileSystem will contain the file, directory, and filesystem files in a module called File. SUFFIX: suffix to implementation (e.g. Posix) ARGN: extra MOD_DEPS to add (e.g. Fw_Time)

Next Topics:

  • Setting Options: Options are used to vary a CMake build.
  • Adding Modules: Modules register fprime Ports, Components, etc.
  • Creating Toolchains: Toolchains setup standard CMake Cross-Compiling.
  • Adding Platforms: Platforms help fprime set Cross-Compiling specific items.
  • Adding Targets: Targets for help defining custom build targets
  • Implementation Packages Design: Implementation Packages