Skip to content

Latest commit

 

History

History
197 lines (143 loc) · 9.35 KB

README.md

File metadata and controls

197 lines (143 loc) · 9.35 KB
Raw

F´ CMake Build System

Stock F´ ships with a bespoke make system ensure that building is done correctly and in the correct order. However, using and maintaining this build system presents a steep learning curve to new users of F´. This included CMake system is intended as an eventual replacement to the existing build system that should be easier to learn and use. In addition, the use of cmake puts F´more in line with standard C++ development.

Since this CMake system ships along-side the original make system, certain caveats must be understood before beginning to use CMake. These caveats should disappear after CMake replaces the original make system in its entirety.

Installation guides for CMake can be found here: https://cmake.org/install/.

Further usage documentation can be found in API.md: API.md. This document will explain the usage of core F´ CMake functions used to construct CMake deployments.

Further discussion regarding transition from the former make system can be found here: Migration.md

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

CMakes Caveats

  1. CMake should not be used in tandem with the original make system. If it is needed to switch between make systems, perform a git clean command or otherwise remove generated files.
  2. CMake in-source builds will be dangerous as auto-generated CMake Makefiles will clobber the existing make system. Use CMake out-of-source builds until the old make system is replaced.

Getting Started Using CMake and F`

CMake as a system auto-generates OS-specific make files for building F´. Once these file are generated, standard make tools can be run to perform the compiling, assembling, linking etc. Building a CMake-enabled deployment comes down to just a small number of steps:

  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>
  3. Engage OS-specific make system: make
  4. Run unit tests: make check
  5. Run F´ specific targets like dictionariy generation, and module coverage: Targets

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 achived as build-artifacts, but are typically not added to source managment (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 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

CMake Options

There are several options that can be specified as part of the CMake system. These options are documented in the following file: Options.md.

Adding in New CMake Components and Deployments

The core of a cmake build is the CMakeLists.txt file. This file specifices 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 deploment 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 setup 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 Toolchain File

Toolchain files are used to setup the tools and packages used to cross-compile code for a separate target platform. The cmake toolchain files are placed in cmake/toolchain and are standard CMake toolchain files. https://cmake.org/cmake/help/v3.12/manual/cmake-toolchains.7.html Alternatively, the user may specify a path to an external CMake toolchain file. This file specifies the path to the tools used to perform the build (i.e. the compilers, libraries, and packages). A sample template for setting up new toolchain files can be found at cmake/toolchain/toolchain.cmake.template. Copy this file to the new toolchain name, fill it out, and it can be then used with the above cross-compile instructions.

Note: a parallel platform file must be created or an exisitng platform file specified with the -DPLATFORM option before a toolchain file can be used.

More information can be found at: template.md. More information can be found at: Options.md.

CMake Platfrom File

Platform files are used to specify CMake options, compile flags, definitions, and other setting used by F´ when compiling for a separate target. These files are F´ specific and are named after the ${CMAKE_SYSTEM_NAME} defined in the toolchain file used to kick-off a cross compile. The platform files are found in cmake/platform. In order to create one of these files, copy the platform template and fill it out. The template for setting up new platform files can be found at cmake/platform/platform.cmake.template Then follow the above instructions to cross-compile.

Note: a parallel toolchain file must exist in order to trigger this platform file unless it is manually specified with the -DPLATFORM option.

More information can be found at: platform.md. More information can be found at: Options.md.

CMake Customization

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

Advanced CMake Usage (Caution: these steps are not polished, hence "Advanced")

CMake supports some advanced build-cases that will soon become standard practice for projects that wish to use F´. These features are less polished than the normal CMake usage but will be developed further as time continues. Thus, basic notes are included here but users should endevour to have solid understanding of CMake before expecting these to work 100%.

These features include:

  1. Building with F´as a Subdirectory/Module

CMake With F´ As a Subdirectory

CMake allows users to setup application outside of the existing fprime directory. This means F´ can be treated as a submodule. This enables a cleaner use of F´ in larger projects. In order to use F´ in this way, the following needed to be taken care of.

  1. F´ autocoded folders should be placed in the build-output. In-source-builds cannot be used.
  2. F´ build-root must be overrided until the AutoCoder is fixed to be BUILD_ROOT independent.

F´ BUILD_ROOT must also be overrided for the non-core components. Otherwise, the auto-coder and other tools will fail. This can be done with the following two lines added to the Deployment CMakeLists.txt. However, these lines must be added after including F´core subdirectories.

# **** First Include FPrime.cmake,FPrime-Code.cmake the core API and components CMakes ***
include("${CMAKE_CURRENT_LIST_DIR}/../cmake/FPrime.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/../cmake/FPrime-Code.cmake")

# **** Second, override the current BUILD_ROOT ****
set(FPRIME_CURRENT_BUILD_ROOT "${CMAKE_CURRENT_LIST_DIR}/..")
message(STATUS "F´ BUILD_ROOT currently set to: ${FPRIME_CURRENT_BUILD_ROOT}")

... add deployment only modules here ...