| .. |
| ******************************************************************************* |
| Copyright (c) 2021 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) |
| 2021 in-tech GmbH |
| |
| This program and the accompanying materials are made available under the |
| terms of the Eclipse Public License 2.0 which is available at |
| http://www.eclipse.org/legal/epl-2.0. |
| |
| SPDX-License-Identifier: EPL-2.0 |
| ******************************************************************************* |
| |
| .. _cmake: |
| |
| CMake Variables and Options |
| =========================== |
| |
| |Op| 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 |op|. 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 and QtCreator can be found under :ref:`vscode` and :ref:`qtcreator`. |
| |
| .. admonition:: 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. :ref:`MSYS2 <msys2>`). |
| |
| .. _cmake_prefix_path: |
| |
| CMAKE_PREFIX_PATH |
| ----------------- |
| |
| This variable makes the prerequisites available to |op| as semicolon-separated list of directories, |
| specifying installation prefixes to be searched by cmake. |
| Please refer to :ref:`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): |
| |
| .. tabs:: |
| |
| .. tab:: Windows |
| |
| .. code-block:: bash |
| |
| 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>\ |
| .. |
| |
| .. tab:: Linux |
| |
| .. code-block:: bash |
| |
| cmake -D CMAKE_PREFIX_PATH=\ |
| $PWD/../deps/thirdParty/linux64/FMILibrary\;\ |
| $PWD/../deps/thirdParty/linux64/osi\;\ |
| $PWD/../deps/thirdParty/linux64/minizip\;\ |
| -D <other variables> \ |
| .. |
| |
| .. warning:: The semicolon ``;`` needs to be escaped (``\;``) unless the string is quoted. |
| |
| .. note:: Please also read through :ref:`cmake_openpass_variables` 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 |
| ---------------- |
| |
| - Specifies the build type on single-configuration generators. |
| - Typical: Release | Debug |
| - See: https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html |
| |
| .. note:: |
| |
| IDEs, as Qt Creator, might set this variable base on the current build type on their own. |
| |
| CMAKE_C_COMPILER |
| ---------------- |
| |
| - Options: **gcc-10** | gcc-9 | gcc-8 |
| - See: https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html |
| |
| .. note:: |
| |
| IDEs, as Qt Creator, might set this variable via *kit* settings. |
| |
| CMAKE_CXX_COMPILER |
| ------------------ |
| |
| - Options: **g++-10** | g++-9 | g++-8 |
| - See: https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html |
| |
| .. note:: |
| |
| IDEs, as Qt Creator, might set this variable via *kit* settings. |
| |
| CMAKE_OBJECT_PATH_MAX |
| --------------------- |
| |
| - Under windows, errors from too long paths could be prevented by setting this value to 255 (maximum). |
| - See: https://cmake.org/cmake/help/latest/variable/CMAKE_OBJECT_PATH_MAX.html |
| |
| .. _cmake_openpass_variables: |
| |
| USE_CCACHE |
| ---------- |
| |
| - Activates ccache (see :ref:`prerequisites_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_COVERAGE |
| ------------- |
| |
| - Add test targets for code coverage analysis (lcov) and HTML report generation (genhtml) |
| - Options: **OFF** | ON |
| - Use ``COVERAGE_EXCLUDE`` to remove folders from the analysis |
| |
| .. note:: |
| |
| The generated files are placed next to the test executable. |
| Each test will be built without optimization, which will increase the testing run-time. |
| |
| WITH_GUI |
| -------- |
| |
| - Activates the additional build of the GUI provided with |Op| (open source). |
| - Options: **OFF** | ON |
| |
| .. note:: |
| |
| Please refer to :ref:`gui_plugins` for information on the GUI. |
| |
| WITH_TESTS |
| ---------- |
| |
| - Build unit tests |
| - Options: OFF | **ON** |
| |
| WITH_ENDTOEND_TESTS |
| ------------------- |
| |
| - Enables execution of end to end tests using :ref:`testing_endtoend`. |
| - 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. |
| |
| .. _cmake_protobuf_arenas: |
| |
| WITH_EXTENDED_OSI |
| ----------------- |
| |
| - When set, assumes that extended version of OSI is available, by enabling the ``USE_EXTENDED_OSI`` preprocessor variable. |
| - This variable can be used to enable e.g. customized OSI features: |
| |
| .. code-block:: c++ |
| |
| #ifdef USE_EXTENDED OSI |
| #include "osi3/osi_<custom_message>.pb.h" |
| #endif |
| |
| - Options: **OFF** | ON |
| |
| WITH_PROTOBUF_ARENA |
| ------------------- |
| |
| - | *Arena allocation is a C++-only feature that helps you optimize your memory usage and improve performance when working with protocol buffers.* |
| | (from https://developers.google.com/protocol-buffers/docs/reference/arenas) |
| - Options: **ON** | OFF |
| |
| .. note:: |
| |
| This feature is only available, if protobuf related libraries are also compiled with arenas (see :ref:`building_osi`). |
| 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: |
| |
| .. code-block:: bash |
| |
| 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** |
| |
| Make Targets/Commands |
| --------------------- |
| |
| |Op| defines build targets by major modules or components, such as ``opSimulation`` or ``Algorithm_FmuWrapper``. |
| After calling CMake, simply build |op| by calling ``make``. |
| |
| .. admonition:: See also |
| |
| https://www.tutorialspoint.com/unix_commands/make.htm |
| |
| Build and Install |
| ~~~~~~~~~~~~~~~~~ |
| |
| - ``make`` |
| |
| - ``make install`` |
| |
| .. warning: |
| |
| - Right now, there is still an issue with an additinal ``bin`` folder. |
| After installing, the content of the `./bin` folder needs to be copied into `.`. |
| |
| - Make install seems to have troubles on some systems when copying the dependencies. |
| Check if the libraries of e.g. OSI are copied into the execution directory of the core. |
| |
| - MinGW system libraries are not a dependency visible to make. |
| |
| - ``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"`` |