Advanced F´ CMake Usage

The CMake system has several advanced usages, described here. This document walks through the CMake usage and settings for users ignoring fprime-util and trying to run the CMake system directly. If a user just wants to configure an IDE integration to use CMake directly, see IDE Configuration first.

Note: fprime-util was designed to ease use of the F´ cmake system by wrapping all of the developer-level processes freeing users from running these steps directly. This automatically handles the two build types using the developer’s action to choose the correct one.

CMake Build Types

fprime allows for two different CMAKE_BUILD_TYPE settings (specified using -DCMAKE_BUILD_TYPE when generating a build cache). These two types are: Release used to build a flight-like executable, and Testing enabling debugging and unit test features. These are split such that testing can be done on a more permissive executable.

Running CMake directly (by hand) amounts to generating a build cache and running make (assuming GNU make output):

1. Make and change to a directory to build in: mkdir build_dir; cd build_dir
2. Call CMake to generate make-files: cmake <path to deployment CMakeLists.txt> -DCMAKE_BUILD_TYPE=<some type>
3. Engage OS-specific make system: make
4. Run unit tests: make check. Note: check is only available in the Testing CMAKE_BUILD_TYPE

Further information on each step is provided below.

Make Build Directory and Generate CMake Files (Run Once Per Configuration)

When building F´ using the CMake system, each build type should be separated into its own directory. Any time a different platform, toolchain, or option set are used, a new directory should be created. However, each of these directories are independent, and can be built independently without cleaning or removing the others.

The following commands will create a new build directory and generate CMake files. Separate builds should be isolated in their own build-directories. These directories can be achieved as build-artifacts, but are typically not added to source management (Git).

Below, a user-provided deployment directory could be substituted for Ref below in-order to build a different deployment. More on deployments below.

Build Setup Commands

# Make a build directory and change directory into it
mkdir fprime/build-dir
cd fprime/build-dir
# Run CMake to generate CMake Files (Specifically for the Ref App)
cmake ../Ref/

Building Deployments (Iterated On Change)

Once generated by CMake, the cmake files typically do not need to be re-generated. If a new configuration is needed, a separate (new) build directory should be used. If changes occur to the CMake system, running the following steps will rerun the CMake file generation. Thus, the above step can be run one time. Rebuilding and iteration can be done with the following simple steps:

Build Commands(Linux, Mac OS X)

# Build the application (Will regenerate CMake if necessary)
make
# Build and run the UTs (if desired)
make check # Only if CMAKE_BUILD_TYPE=Testing was used when generating the build cache

Adding in New CMake Components and Deployments

The core of a cmake build is the CMakeLists.txt file. This file specifies the files needed to build the current directory of the system. In F prime each Component, Port, and Topology get a CMakeList.txt along with the top-level deployment directory.

Two templates for these CMakeLists.txt files are provided as part of the CMake system. One for Modules that result in the creation of a library, executable, or both. The other for Deployments, which setup the CMake for a deployment and include a number of Modules.

Components, Ports, and Topologies (Top folders) all use the Module template. These modules provide libraries and executables to the system.

Top-level deployment directories (Ref folder) use the deployment templates. It is there to setup the entry point to the build system.

For more on Modules, see: module.md For more on Deployments, see: deployment.md

Cross-Compiling With CMake

In order to cross-compile F´ with the cmake system to some new target platform, two files are required. These two files are a cmake toolchain file, and an F´ platform file. Once these files have been created, a cross-compile can be set up and run with the following commands:

mkdir build-cross
cd build-cross
cmake -DCMAKE_TOOLCHAIN_FILE=<path/to/toolchain/file> <path/to/deployment>
make

CMake Customization

Sometimes users need to crack open the CMake structure in order to do things like adding an external library/build system, adding custom make targets, building utilities, etc. These issues are described here: Customization

Further documentation can be found in the SDD: SDD.md