Skip to content

Utilities

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

utilities.cmake:

Utility and support functions for the fprime CMake build system.

Function sort_buildable_from_non_buildable_sources:

Sorts C/C++ "buildable" sources from other sources. This uses the GLOBAL property C_CPP_ASM_REGEX to determine how to sort. Ideally users would use SOURCES and AUTOCODER_INPUTS to distinguish but this provides some backwards compatibility with the merged SOURCE_FILES variable.

  • BUILDABLE_SOURCE_OUTPUT: output name for buildable sources to be set in parent scope
  • NON_BUILDABLE_SOURCE_OUTPUT: output name for non-buildable sources to be set in parent scope

Macro clear_historical_variables:

Clears old variables MOD_DEPS, SOURCE_FILES, HEADER_FILES, etc. from the scope of the caller. This removes accidental uses of these variables within the refactored system from this scope and below.

This is a macro to ensure the caller's scope is affected.

ARGN: passed to the unset calls (for things like PARENT_SCOPE)

Function plugin_name:

From a plugin include path retrieve the plugin name. This is the name without any .cmake extension.

INCLUDE_PATH: path to plugin OUTPUT_VARIABLE: variable to set in caller's scope with result

Function plugin_include_helper:

Designed to help include API files (targets, autocoders) in an efficient way within CMake. This function imports a CMake file and defines a dispatch_<function>(PLUGIN_NAME ...) function for each function name in ARGN. Thus users of the imported plugin can call dispatch_<function>(PLUGIN_NAME ...) to dispatch a function as implemented in a plugin.

OUTPUT_VARIABLE: set with the plugin name that has last been included INCLUDE_PATH: path to file to include

starts_with:

Check if the string input starts with the given prefix. Sets OUTPUT_VAR to TRUE when it does and sets OUTPUT_VAR to FALSE when it does not. OUTPUT_VAR is the name of the variable in PARENT_SCOPE that will be set.

Note: regexs in CMake are known to be inefficient. Thus starts_with and ends_with are implemented without them in order to ensure speed.

OUTPUT_VAR: variable to set STRING: string to check PREFIX: expected ending

ends_with:

Check if the string input ends with the given suffix. Sets OUTPUT_VAR to TRUE when it does and sets OUTPUT_VAR to FALSE when it does not. OUTPUT_VAR is the name of the variable in PARENT_SCOPE that will be set.

Note: regexs in CMake are known to be inefficient. Thus starts_with and ends_with are implemented without them in order to ensure speed.

OUTPUT_VAR: variable to set STRING: string to check SUFFIX: expected ending

init_variables:

Initialize all variables passed in to empty variables in the calling scope.

normalize_paths:

Take in any number of lists of paths and normalize the paths returning a single list. OUTPUT_NAME: name of variable to set in parent scope

resolve_dependencies:

Sets OUTPUT_VAR in parent scope to be the set of dependencies in canonical form: relative path from root replacing directory separators with "_". E.g. fprime/Fw/Time becomes Fw_Time.

OUTPUT_VAR: variable to fill in parent scope ARGN: list of dependencies to resolve

Function is_target_real:

Does this target represent a real item (executable, library)? OUTPUT is set to TRUE when real, and FALSE otherwise. Non-real targets include TARGET_TYPE=UTILITY and ALIASED_TARGET.

OUTPUT: variable to set TEST_TARGET: target to set

Function is_target_library:

Does this target represent a real library? OUTPUT is set to TRUE when real, and FALSE otherwise.

OUTPUT: variable to set TEST_TARGET: target to set

linker_only:

Checks if a given dependency should be supplied to the linker only. These will not be supplied as CMake dependencies but will be supplied as link libraries. These tokens are of several types:

  1. Linker flags: starts with -l
  2. Existing Files: accounts for preexisting libraries shared and otherwise

OUTPUT_VAR: variable to set in PARENT_SCOPE to TRUE/FALSE TOKEN: token to check if "linker only"

Function get_nearest_build_root:

Finds the nearest location in FPRIME_LOCATIONS to the given path. This is used for calculating module names, include paths, and relative asserts. FPRIME_LOCATIONS is derived from the global interface target.

Note: historically these were called "build roots".

  • DIRECTORY_PATH: path to detect nearest build root Return: nearest parent from FPRIME_LOCATIONS as read from the global interface target property FPRIME_LOCATIONS

Function get_module_name:

Takes a path, or something path-like and returns the module's name. This breaks down as the following:

  1. If passed a path, the module name is the '_'ed variant of the relative path from BUILD_ROOT
  2. If passes something which does not exist on the file system, it is just '_'ed

i.e. ${BUILD_ROOT}/Svc/EventManager becomes Svc_EventManager Svc/EventManager also becomes Svc_EventManager

  • DIRECTORY_PATH: (optional) path to infer MODULE_NAME from. Default: CMAKE_CURRENT_LIST_DIR
  • Return: MODULE_NAME (set in parent scope)

Function get_expected_tool_version:

Gets the expected tool version named using version identifier VID to name the tools package file. This will be returned via the variable supplied in FILL_VARIABLE setting it in PARENT_SCOPE.

Function set_assert_flags:

Adds a -DASSERT_FILE_ID=(First 8 digits of MD5) to each source file, and records the output in hashes.txt. This allows for asserts on file ID not string. Also adds the -DASSERT_RELATIVE_PATH flag for handling relative path asserts.

Function print_property:

Prints a given property for the module. - TARGET: target to print properties - PROPERTY: name of property to print

Function introspect:

Prints the dependency list of the module supplied as well as the include directories.

  • MODULE_NAME: module name to print dependencies

Function execute_process_or_fail:

Calls CMake's execute_process with the arguments passed in via ARGN. This call is wrapped to print out the command line invocation when CMAKE_DEBUG_OUTPUT is set ON, and will check that the command processes correctly. Any error message is output should the command fail. No handling is done of standard error.

Errors are determined by checking the process's return code where a FATAL_ERROR is produced on non-zero.

  • ERROR_MESSAGE: message to output should an error occurs

Function append_list_property:

Appends the NEW_ITEM to a property. ARGN is a set of arguments that are passed into the get and set property calls. This function calls get_property with ARGN appends NEW_ITEM to the result and then turns around and calls set_property with the new list. Callers should not supply the variable name argument to get_property.

Duplicate entries are removed.

Args: - NEW_ITEM: item to append to the property - ARGN: list of arguments forwarded to get and set property calls.

Function get_fprime_library_option_string:

Returns a standard library option string from a name. Library option strings are derived from the directory and converted to a set of valid characters: [A-Z0-9_]. Alphabetic characters are made uppercase, numeric characters are maintained, and other characters are replaced with _.

If multiple directories convert to the same name, these are effectively merged with respect to library options.

OUTPUT_VAR: output variable to be set in parent scope LIBRARY_NAME: library name to convert to option

Function resolve_path_variables:

Resolve paths updating parent scope. ARGN should contain a list of variables to update.

ARGN: list of variables to update

Function fprime_glob_ordered:

Runs file(GLOB) for each pattern in a list individually and appends results in order. This preserves the priority of earlier patterns over later ones, unlike a single GLOB call which returns all results in lexicographic order regardless of pattern ordering. Duplicates are removed while preserving the order of first occurrence. Uses GLOB (not GLOB_RECURSE) so that wildcards match a single directory level only.

  • OUTPUT_VAR: variable name to store the accumulated results in (set in PARENT_SCOPE)
  • ARGN: glob patterns to search, in priority order

Function fprime_cmake_fatal_error:

Prints a fatal error message to the user, highlighted with ---- to make it obvious. For multi-line messages, place a \n at the end of the previous message.

  • ARGN: message(s) to print separated by ' 's

Function fprime_cmake_warning:

Prints a warning message to the user, highlighted with ---- to make it obvious. For multi-line messages, place a \n at the end of the previous message.

  • ARGN: message(s) to print separated by ' 's

Function fprime_cmake_status:

Prints a status message to the user that can be quieted with FPRIME_CMAKE_QUIET=ON. - ARGN: arguments to CMake's message() function w/o severity level

Function fprime_cmake_debug_message:

Prints a debug message.

  • MESSAGE: message to print

Function fprime__cmake_clear_message:

Prints a message to the user, highlighted with ---- to make it obvious and including the list file that is failing. For multi-line messages, place a \n at the end of the previous message.

  • SEVERITY: message severity to use
  • ARGN: message(s) to print separated by ' 's

Macro fprime_cmake_ASSERT:

Checks condition, prints message. This is a macro so the condition is pasted into the message as well as the conditional clause.

  • CONDITION: condition to evaluate with if (${CONDITION})

Function recurse_target_properties:

Recurses the supplied PROPERTY_NAMES of the CMAKE_BUILD_TARGET_NAME target. Sets three variables TRANSITIVE_LINKS_OUTPUT, EXTERNAL_LINKS_OUTPUT, and NON_EXISTENT_LINKS_OUTPUT. Where TRANSITIVE_LINKS_OUTPUT holds the transitive values of target/links found in those properties (recursively), EXTERNAL_LINKS_OUTPUT holds IMPORTED type targets found in the recursion, and NON_EXISTENT_LINKS_OUTPUT holds unknown/non-target values found (recursively).

NON_EXISTENT_LINKS_OUTPUT will include directly linked files, linker flags, and other non-target values.

Warning

Properties supplied through PROPERTY_NAMES must be composed of mostly target names (e.g. LINK_LIBRARIES, MANUALLY_ADDED_DEPENDENCIES, etc.)

  • CMAKE_BUILD_TARGET_NAME: name of the target in the CMake system
  • PROPERTY_NAMES: list of properties containing other CMake target names to be read recursively
  • TRANSITIVE_LINKS_OUTPUT: name of output to write transitive links/dependencies in PARENT_SCOPE
  • EXTERNAL_LINKS_OUTPUT: name of output to write external (IMPORTED) links/dependencies in PARENT_SCOPE
  • NON_EXISTENT_LINKS_OUTPUT: name of output to write non-target links/dependencies in PARENT_SCOPE

Function fprime__internal_target_interceptor:

A function that intercepts calls to target_* functions and translates the scope from PUBLIC to INTERFACE when the target is an INTERFACE target.

  • FUNCTION_NAME: name of the target_* function to intercept
  • BUILD_TARGET_NAME: name of the target to set
  • SCOPE: scope of the target to intercept and change
  • ARGN: arguments to pass to the target_* function

This function wraps target_link_libraries to ensure that PUBLIC scope additions translate to INTERFACE when the target is an INTERFACE target. This makes it easier to deal with INTERFACE targets.

See: target_link_libraries

Function fprime_target_include_directories:

This function wraps target_include_directories to ensure that PUBLIC scope additions translate to INTERFACE when the target is an INTERFACE target. This makes it easier to deal with INTERFACE targets.

See: target_include_directories

Function fprime_target_dependencies:

Adds dependencies to the supplied BUILD_TARGET_NAME properly handling scope (see fprime_target_link_libraries). Adding a dependency involves 2 steps: 1. Adding a link dependency from BUILD_TARGET_NAME to supplied dependencies 2. Append supplied dependencies to the FPRIME_DEPENDENCIES property of BUILD_TARGET_NAME

  • BUILD_TARGET_NAME: name of the target to add dependencies to
  • SCOPE: scope of the target to intercept and change from PUBLIC to INTERFACE for INTERFACE_LIBRARY targets targets
  • ARGN: dependencies to add to the target