..
  *******************************************************************************
  Copyright (c) 2021-2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
                2023 Mercedes-Benz Tech Innovation 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
  *******************************************************************************

External Dependencies
=====================

|OP| depends on a number of external dependencies. Installation of those dependencies is described in :ref:`prerequisites`.

The third party software dependency of |op| can be divided into:

- **Build environment**, which manages third party software and is used to compile and install |op|
- **Binary packages**, which can be easily installed via a package manager of the respective build environment
- **Source packages**, which need to be built from source code

This section gives an overview of the dependencies and how they are used.

Information on Binary Packages
------------------------------

GNU Compiler Collection (gcc)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Version (latest tested): |gcc_version|

|Op| is developed on Linux and Windows (64-Bit) in `C++17 <https://isocpp.org/>`_ using the GNU Compiler Collection (`gcc <https://gcc.gnu.org/>`_).

.. admonition:: Useful hints

   - | |op| has been developed using gcc 7.x, 8.x, 9.x, and more recently gcc 10.x.
      | There are no known issues regarding the different versions.
   - Since no compiler specific features are used, the source should also compile with `clang <https://clang.llvm.org/>`_.
   - Generally, there is support for `MSVC <https://docs.microsoft.com/en-us/cpp/build/reference/c-cpp-building-reference>`_ , but currently not actively maintained by the |opwg|.

GNU Debugger (gdb)
~~~~~~~~~~~~~~~~~~

Version (latest tested): |gdb_version|

Debugging tools for gcc: https://www.gnu.org/savannah-checkouts/gnu/gdb/index.html

CMake
~~~~~

Version (latest tested): |cmake_version|

|Op| uses `CMake <https://cmake.org/>`_ for building and testing.
For details on the provided options, see :ref:`cmake`.

.. _prerequisites_ccache:

Ccache
~~~~~~

Version (latest tested): |ccache_version|

|Op| supports the compiler cache `Ccache <https://ccache.dev/>`_ for faster recompilation.
Use only, if you need to recompile regularly.

.. admonition:: Useful hints

   - The first compilation is definilty slower (e.g. by 30%), as the cache needs to be built.
   - If used regularily, increasing the cache size is recommended, e.g.: ``ccache -M 20G``

Doxygen
~~~~~~~

Version (latest tested): |doxygen_version|

Documentation is created using `Doxygen <https://www.doxygen.nl/index.html>`_.

.. admonition:: Useful hints

   - Doxygen introduced support for Markdown with 1.8, which is still in use.
      Don't use older versions.

Boost C++ Libraries
~~~~~~~~~~~~~~~~~~~

Version (officially supported): |boost_version|

Especially for geometrical calculations, |op| uses parts of the `Boost C++ Libraries <https://www.boost.org/>`_.

.. admonition:: Note on Versions

   More recent versions should integrate without issues, but 1.74.0 already raise warnings for some deprecated headers.

googletest
~~~~~~~~~~

Version (officially supported): |gtest_version|

Tests are written in `googletest <https://github.com/google/googletest>`_ and |Op| makes use of the included *googletest* (gtest) C++ testing framework, as well as the included mocking framework *googlemock* (gmock).

.. note::

   The lastest major release brought several API changes, which made some code fixes necessary.
   Use newer versions with precaution.

Information on Source Packages
------------------------------

The second and last set of dependencies we need to dissolve are based on source packages.
Since installing such source packages is not easy, we have dedicated a separate chapter on this topic.
See :ref:`building_prerequisites` for a step-by-step instruction on how to download, build and install needed source packages.

Details on source packages:

.. _prerequisites_osi:

Open Simulation Interface (OSI)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Version (officially supported): |osi_version|

The internal world representation uses the `Open Simulation Interface <https://github.com/OpenSimulationInterface>`_ (:term:`OSI`) as part of its ground truth (backend storage) and exchange format.

.. figure:: ./_static/draw.io/osi_in_openpass.png

   OSI in |op|

Interaction between World and consumers of OSI messages.

Thereby, OSI provides data structures for representation of various objects in traffic simulation environments.
Note that OSI is primarily developed in a sensor centric view, such as lane markings and object boundaries.
Beyond that, |op| holds data for non-sensor centric data, such as metainfo on lanes and roads.

As shown, OSI itself depends on :ref:`prerequisites_protobuf`.
If not already installed, the library and headers have to be built prior to OSI.

.. _prerequisites_protobuf:

Protocol Buffers (protobuf)
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Supported Version (officially supported): |protobuf_version|

:ref:`prerequisites_osi` uses `Protocol Buffers <https://developers.google.com/protocol-buffers>`_ for describing and serialization of its datastructures.

.. admonition:: Note on Versions

   - So far, no version limitations known (including 2.x).
   - |Op| lets you integrate your own protobuf libraries if necessary.

Modelon FMI Library (FMIL)
~~~~~~~~~~~~~~~~~~~~~~~~~~

Supported Version: |fmi_version|

For integration of Functional Mock-up Units (FMUs) the `Algorithm_FmuWrapper` uses the `Modelon FMI Library <https://github.com/modelon-community/fmi-library>`_.
As there is no binary available, FMIL needs to be build from scratch before |op| can be compiled.