CMake Variables and Options

openPASS uses CMake as default cross-platform build environment. CMake varibles describe configuration settings, which can be overriden by the user. To override any build configuration, the CMake variables have to be provided when CMake gets run.

If available, recommended options are shown in bold.

The following guide is structered as follows: The first part describes the available variables and options. There are standard CMake variables which are marked with the prefix CMAKE_ and other defined variables used internally to further specify the build of openPASS. As the result of a proper CMake call is a Makefile, which then acts as base for the actual build using make, the second part describes best practices around the make commands using make.

Note, this guide approaches CMake from the command line perspective. Adjustments for VSCode can be found under Working with Visual Studio Code.

See also

CMake Documentation: https://cmake.org/cmake/help/latest/index.html

CMake Generator

This is only important for Windows. To generate MSYS compatible makefiles use -G "MSYS Makefiles" (c.f. MSYS2).

CMAKE_PREFIX_PATH

This variable makes the prerequisites available to openPASS as semicolon-separated list of directories, specifying installation prefixes to be searched by cmake. Please refer to Installing Prerequisites for the list of mandatory packages and libraries. CMake will issue an error, if one prerequisite is missing.

Generally, cmake recognizes installed libraries (e.g. googletest) on its own. By setting an explicit CMAKE_PREFIX_PATH for a library, it is possible to override the system libraries. Use this, when an exact library version, or a customized library shall be used.

Note

In the following example, non-standard libraries are assumed to be in the folder deps/thirdParty.

Example (system libraries not set):

cmake -G "MSYS Makefiles"
      -D CMAKE_PREFIX_PATH="\
         /mingw64/bin;\
         $PWD/../deps/thirdParty/win64/FMILibrary;\
         $PWD/../deps/thirdParty/win64/osi;\
         $PWD/../deps/thirdParty/win64/minizip;\
      -D <other variables>\
      ..

Note

Please also read through USE_CCACHE for further useful hints, e.g. why explicitly setting the MinGW path might be a necessary in some situations.

Installation directory

CMAKE_INSTALL_PREFIX

  • Install directory used by install, when invoking make install

  • Recommendation: /openPASS/bin/core (Linux) | C:/openPASS/bin/core (Windows)

CMAKE_WITH_DEBUG_POSTIX

  • Used only in conjunction with Visual Studio Debug Builds (MSVC), as it distinguishes release/debug DLLs by a postfix d.

  • Options: OFF | ON

CMAKE_BUILD_TYPE

CMAKE_C_COMPILER

CMAKE_CXX_COMPILER

CMAKE_OBJECT_PATH_MAX

USE_CCACHE

  • Activates ccache (see Ccache)

  • Options: ON | OFF

WITH_SIMCORE

  • Build OSI based scenario simulation, also know as openPASS simulation core (opSimulation).

  • Options: OFF | ON

WITH_DOC

  • Build sphinx based documentation

  • Options: OFF | ON

WITH_API_DOC

  • Build sphinx based developer documentation

  • Options: OFF | ON

Note

Automatically activates WITH_DOC if ON

Warning

Building the API doc takes pretty long.

WITH_TESTS

  • Build unit tests

  • Options: OFF | ON

WITH_COVERAGE

Warning

This option turns off optimization, which might make execution considerably slower. In exchange, a coverage <test_name>.info` and HTML reports will be generated in a folder called coverage within the cmake build folder.

  • For each registered test target (see add_openpass_target in ./cmake/HelperMacros.cmake) two more targets are added. One for code coverage analysis using lcov (target <test_name>_coverage). A second for HTML report generation using genhtml (target <test_name>_html).

  • In addition to the individual tests, an overall test target TestCoverageReport is created. When invoked, it will execute all individual tests and combine their coverage data into a single report found in coverage/TestCoverageReport.

  • Options: OFF | ON

  • Requires:

    • WITH_TESTS=ON

    • gcov, lcov, fastcov (python)

  • Parameterization:

    • COVERAGE_EXCLUDES allows to remove source files from report (substring matching), i.e. /usr/include.

    • Multiple paths have to be separated by spaces.

    • Paths specified through CMAKE_PREFIX_PATH and tests/ are filtered by default.

    Warning

    Excluding too many paths or files may lead to an empty <test_name>.info file, causing the HTML target to fail.

WITH_ENDTOEND_TESTS

  • Enables execution of end to end tests using EndToEnd Test Framework.

  • Tests can be ran by executing make install && make pyOpenPASS

  • Options: OFF | ON

OPENPASS_ADJUST_OUTPUT

  • Adjusts if builds are executed in the (CMake default) folder build or directly in the specified install directory. Latter let you skip the call make install.

  • Options: OFF | ON

Warning

When skipping make install, dependencies are not copied into the output folder, which could cause crashes due to missing or outdated libraries.

WITH_PROTOBUF_ARENA

Note

This feature is only available, if protobuf related libraries are also compiled with arenas. Fortunately, the implementation falls back to regular allocation if not, which simply results in less performance.

INSTALL_SYSTEM_RUNTIME_DEPS

  • during installation step, this configuration copies detected system runtime dependencies to install directory (i.e. MinGW system libraries)

  • Options: ON | OFF

Warning

Under windows, automatic resolution might fail if other MinGW instances are installed. As several programs use MinGW under the hood, it is recommended to set the used MinGW path in the CMAKE_PREFIX_PATH explicitly:

CMAKE_PREFIX_PATH = mingw64/bin;\...

INSTALL_EXTRA_RUNTIME_DEPS

  • during installation step, this configuration copies detected runtime dependencies (i.e. required shared libraries) specified in CMAKE_PREFIX_PATH to install directory

  • Options: ON | OFF

INSTALL_EXAMPLES

  • If ON, opSimulation configuration examples are copied to the examples folder inside the installation directory (during the installation step).

  • Options: ON | OFF

Make Targets/Commands

openPASS defines build targets by major modules or components, such as opSimulation or Algorithm_FmuWrapper. After calling CMake, simply build openPASS by calling make.

See also

https://www.tutorialspoint.com/unix_commands/make.htm

Build and Install

  • make

  • make install

  • make <target>: Build a single target

Executing Tests

  • All tests: make test ARGS="--output-on-failure -j3"

  • Single test: make test opSimulation_Tests ARGS="--output-on-failure -j3"