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_LOCATIONS of the global interface.

See: https://cmake.org/cmake/help/latest/command/add_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_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
    LINK_DEPENDS
        ${CMAKE_CURRENT_SOURCE_DIR}/extra_file.ld
)

Note

This delegates to CMake's add_library call. The library argument EXCLUDE_FROM_ALL is supported. The LINK_DEPENDS directive accepts a list of extra files (e.g. linker scripts) that should trigger a rebuild when they change.

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
    LINK_DEPENDS
        ${CMAKE_CURRENT_SOURCE_DIR}/linker_script.ld
)

Note

This delegates to CMake's add_executable call. The argument EXCLUDE_FROM_ALL is supported. The LINK_DEPENDS directive accepts a list of extra files (e.g. linker scripts) that should trigger a rebuild when they change.

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
    LINK_DEPENDS
        ${CMAKE_CURRENT_SOURCE_DIR}/linker_script.ld
)

Note

This delegates to CMake's add_executable call. The argument EXCLUDE_FROM_ALL is supported. The LINK_DEPENDS directive accepts a list of extra files (e.g. linker scripts) that should trigger a rebuild when they change.

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 module using the fprime build system. This comes with dependency management and fprime autocoding capabilities. The call format is identical to register_fprime_library (SOURCES, AUTOCODER_INPUTS, HEADERS, DEPENDS, INTERFACE, EXCLUDE_FROM_ALL) and additionally supports the following directives:

CONFIGURATION_OVERRIDES: files replacing configuration files supplied by a previously registered configuration module (framework defaults, platform, library, or subtopology configuration). An override is matched to the file it replaces by file name only and is copied into the original module's location in the build cache. Listing a file that no earlier module supplied is an error.
GLOBAL_IMPLICIT_DEPENDENCY: links the configuration module into the global interface target. Every module that transitively depends on Fw_Types (i.e. all F Prime modules) then receives the configuration's include root and link dependency without listing the module in DEPENDS. Used by the framework defaults and by platform configuration; library authors may use it to make their default configuration implicitly available to everything in the build. Configuration not marked this way must be listed in DEPENDS by the modules that use it. A module marked this way must not list Fw_Types in DEPENDS (Fw_Types depends on the global interface target, so the dependency would be circular and is rejected under BUILD_SHARED_LIBS=ON); depend on ${FPRIME_GLOBAL_INTERFACE_TARGET} instead, as default/config does.
CHOOSES_IMPLEMENTATIONS: implementations (e.g. Os_File_Posix) selected by this configuration. See register_fprime_implementation.

Note

GLOBAL_IMPLICIT_DEPENDENCY replaces the BASE_CONFIG flag, which is deprecated and will be removed in a future release. BASE_CONFIG remains a synonym and emits a deprecation warning.

All configuration module sources (SOURCES, HEADERS, and AUTOCODER_INPUTS) are copied into the build cache and are included via the parent of the module's build directory, i.e. a header registered from default/config/FpConfig.h is included as config/FpConfig.h. The source directory must therefore not sit directly under a source include root (project root, framework root, or library root), otherwise the source-tree file shadows the build cache copy; this is detected for SOURCES and HEADERS (not AUTOCODER_INPUTS or CONFIGURATION_OVERRIDES) and reported as an error. Configuration files are processed in order of detection within the CMakeLists.txt tree, and the last registration of a given file name wins:

platform -> framework defaults (default/config) -> libraries -> project.

Modules supplying SOURCES or AUTOCODER_INPUTS must be STATIC libraries (or INTERFACE when nothing compiles), so that they can depend on Fw_Types regardless of the Fw_Types library type (e.g. BUILD_SHARED_LIBS=ON). Declare STATIC explicitly whenever the module supplies SOURCES: the automatic STATIC default currently applies only to modules with AUTOCODER_INPUTS (see https://github.com/nasa/fprime/issues/5970). Modules supplying only HEADERS and/or CONFIGURATION_OVERRIDES must be declared INTERFACE (CMake otherwise fails at generate time with "No SOURCES given to target").

See the user manual for the full description: docs/user-manual/build-system/configuration.md

Warning

Headers must be listed under HEADERS to be treated as configuration.

Example:

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

Example library default configuration (my-library/default-config/config-my-library/CMakeLists.txt), implicitly available to all modules:

register_fprime_config(
        config-my-library
    HEADERS
        MyLibraryCfg.hpp
    AUTOCODER_INPUTS
        MyLibraryCfg.fpp
    GLOBAL_IMPLICIT_DEPENDENCY
)

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) fprime_cmake_debug_message("[target] Registering custom target: ${TARGET_FILE_PATH}") 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)

Macro `register_fprime_project`:

Used to register an F Prime project. This will do the following: 1. Add the current source directory to the FPRIME_LOCATIONS property of the global interface 2. Add the current binary directory to the FPRIME_LOCATIONS property of the global interface 3. Add the current source directory to the global include directories 4. Add the current binary directory to the global include directories 5. Add the current source directory to the CMAKE_PATH_PREFIX variable for this module This allows it to be found and used by other modules in the build system. It ensures that the components are properly slotted underneath this library for the purpose of include path and target names. Args: none

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

API

API.cmake:

Macro skip_on_sub_build:

Macro restrict_platforms:

Function add_fprime_subdirectory:

Function fprime_attach_custom_targets:

Function register_fprime_library:

Function register_fprime_module:

Function fprime_add_library_build_target:

Function register_fprime_executable:

Function fprime_add_executable_build_target:

Function register_fprime_deployment:

Function fprime_add_deployment_build_target:

Function register_fprime_config:

Function fprime_add_config_build_target:

Function register_fprime_ut:

Function fprime_add_unit_test_build_target:

Macro register_fprime_target:

Macro register_fprime_list_helper:

Macro register_fprime_build_autocoder:

Function create_implementation_interface:

Function register_fprime_implementation:

Adds a named os implementation.

Macro register_fprime_project:

Next Topics:

Macro `skip_on_sub_build`:

Macro `restrict_platforms`:

Function `add_fprime_subdirectory`:

Function `fprime_attach_custom_targets`:

Function `register_fprime_library`:

Function `register_fprime_module`:

Function `fprime_add_library_build_target`:

Function `register_fprime_executable`:

Function `fprime_add_executable_build_target`:

Function `register_fprime_deployment`:

Function `fprime_add_deployment_build_target`:

Function `register_fprime_config`:

Function `fprime_add_config_build_target`:

Function `register_fprime_ut`:

Function `fprime_add_unit_test_build_target`:

Macro `register_fprime_target`:

Macro `register_fprime_list_helper`:

Macro `register_fprime_build_autocoder`:

Function `create_implementation_interface`:

Function `register_fprime_implementation`:

Macro `register_fprime_project`: