# Installing Prerequisites

Before being able to compile and run openPASS, make sure to have all dependencies installed. The third party software dependency of openPASS can be divided into:

- Build environment, which manages third party software and is used to compile and install openPASS

- 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 detailed information about the prerequisites and tested version.

## Installing the Build Environment

1. MSYS2

   On Windows, the build environment of choice are MSYS2 programming tools. MSYS2 is used to install some third-party software on which openPASS depends. Also, the unix-like shell simplifies c++ compilation on Windows. For details, see MSYS2 website.

2. Download MSYS2

   The latest 64-bit package is located in the Installation section of MSYS2 website.

3. Install MSYS2

   Run the downloaded executable and adjust suggested settings to your needs (defaults are fine).

   Installation Path

   It is assumed that MSYS2 is installed in the directory `C:\op\msys64`, as our CI scripts depend on this specific path. If you choose to install MSYS2 in a different location, please ensure that you update any related configurations to reflect the new installation path, such as the conan profiles mentioned below.”

4. Understand the Build Environment

   MSYS2 provides three different environments, located in the MSYS2 installation directory:

   MSYS2 Environments

   - MSYS2 MSYS: Common environment, i.e. for package management

   - MSYS2 MinGW 32-bit: A MinGW 32-bit environment

   - MSYS2 MinGW 64-bit: A MinGW 64-bit environment

   Warning

   MSYS2 MinGW 64-bit is the openPASS development environment and will be referred to as `MinGW 64-bit` shell.

On Linux, no special build environment is needed. openPASS is developed under Debian 64-Bit, which means that developing under a recent Ubuntu distribution will also work. Debian Bookworm or Ubuntu 22.04 LTS is recommended. Debian uses `apt` (or `apt-get`) as package managing system. Details will be given in Installing the Binary Packages and Installing the Dependencies.

## Installing the Binary Packages

The first set of dependencies we need to install in order to successfully compile openPASS are the binary packages. These can be installed via appropiate package manager.

1. Open `MSYS2 MinGW 64-bit` and execute the following package manager `pacman` commands to update the package repository and upgrade system packages:

       pacman -Syuu

   If the upgrade requires a restart of MSYS2, resume the upgrade by re-opening the shell and call:

       pacman -Suu

2. Required packages (can be specified in single command line if desired):

       pacman -S  \
           `# for building and running the simulator` \
           make \
           mingw-w64-x86_64-ccache \
           mingw-w64-x86_64-cmake \
           mingw-w64-x86_64-doxygen \
           mingw-w64-x86_64-gcc \
           mingw-w64-x86_64-gdb \
           mingw-w64-x86_64-graphviz \
           mingw-w64-x86_64-make \
           patch \
           `# for documentation` \
           mingw-w64-x86_64-python \
           mingw-w64-x86_64-python-pip \
           mingw-w64-x86_64-python-lxml \
           `# fonts and equation rendering in the documentation` \
           mingw-w64-x86_64-texlive-bin \
           mingw-w64-x86_64-texlive-core \
           mingw-w64-x86_64-texlive-font-utils \
           mingw-w64-x86_64-texlive-latex-extra \
           mingw-w64-x86_64-zziplib \
           `# documentation with only pacman` \
           libxslt-devel \
           mingw-w64-x86_64-python-sphinx \
           mingw-w64-x86_64-python-sphinx-tabs \
           mingw-w64-x86_64-python-sphinx_rtd_theme \
           mingw-w64-x86_64-python-setuptools \
           mingw-w64-x86_64-python-myst-parser \
           `# for testing (optional)` \
           mingw-w64-x86_64-python-pytest \
           mingw-w64-x86_64-python-pandas \
           `# for developing purposes (optional)` \
           mingw-w64-x86_64-clang

   Versions

   MSYS2 provides rolling release versions, so some packages might be too “up-to-date”.

3. Required python packages

       pip3 install "approvaltests==3.1.0" breathe "conan>2.0" empty-files exhale watchdog

GIT/SSH

The `MinGW 64-bit` shell does not access an already existing git installation or available SSH keys. Make sure, to update/copy your configuration and credentials within the `MinGW 64-bit` shell before working with git.

1. Update the package database on the system

       apt update

2. Upgrade existing software to latest version

       apt upgrade

3. Install required binary packages

       # for simulator
       apt -y install antlr4
       apt -y install build-essential
       apt -y install ca-certificates
       apt -y install ccache
       apt -y install cmake
       apt -y install clang-format-15
       apt -y install doxygen
       apt -y install g++
       apt -y install gcc
       apt -y install git
       apt -y install googletest
       apt -y install graphviz
       apt -y install libboost-filesystem-dev
       apt -y install libprotobuf-dev
       apt -y install libantlr4-runtime4.9
       apt -y install libantlr4-runtime-java
       apt -y install libantlr4-runtime-dev
       apt -y install openjdk-17-jre
       apt -y install pkg-config
       apt -y install protobuf-compiler
       apt -y install python3
       apt -y install python3-distutils
       apt -y install python3-pip
       apt -y install uuid-dev

       # python packages
       pip3 install "approvaltests==3.1.0" empty-files "conan>2.0" watchdog
       pip3 install breathe exhale myst-parser "sphinx==7.2.6" sphinx-rtd-theme sphinx-tabs sphinxcontrib-spelling

EndToEnd Test Framework

If end to end tests shall be executed, additional requirements have to be considered. Please refer to EndToEnd Test Framework for more details on installation of the prerequisites and usage of the framework.

## Installing the Dependencies

This section describes how to compile prerequisites of openPASS using conan (`conan>2.0`).

The goal of this section is to build and install necessary packages into a suitable directory using conan.

Note

If you are unfamiliar to `conan` or working with it, Section Building with Conan might give you a short introduction on conan in the scope of building dependencies for openPASS.

To keep the installation process of openPASS and its dependencies as simple as possible, we recommend a specific folder structure. If you strictly follow the recommended paths of this guide, no command modifications are necessary.

- Recommended checkout path of openPASS repository: `C:\openpass`

- Dependency directory within the openPASS repository: `C:\deps`

- Recommended installation directory of openPASS: `C:\openPASS\bin\core`

- Recommended checkout path of openPASS repository: `~/openpass`

- Dependency directory within the openPASS repository: `~/deps`

- Recommended installation directory of openPASS: `/usr/local/openPASS/bin/core`

The above directory structure will be created by following the instructions of this guide.

1. Clone openPASS repository

   As described above, the checkout path of the repository is assumed to be the default `openpass`.

   Start `MinGW 64-bit` shell

       cd /C/
       git clone https://gitlab.eclipse.org/eclipse/openpass/opSimulation.git openpass

   Note

   As stated in Installing the Build Environment, the windows programming tools suffer from a path length restriction. This error manifests as strange file not found compile errors. It is therefore recommended to use a short path for source code checkout, e.g. a drive letter. This can also be done by the windows command subst.

   Start `Bash` shell

       cd ~
       git clone https://gitlab.eclipse.org/eclipse/openpass/opSimulation.git openpass

2. Navigate into repository and checkout main branch

       cd openpass
       git checkout main

3. The essential packages necessary for openPASS are listed in the file `utils/ci/conan/conanfile.txt`.

   If a required package is available on ConanCenter, they will be used directly. For packages not available on ConanCenter, the respective recipes are stored in the `utils/ci/conan/recipe` folder.

   Note

   It is important to have conancenter remote enabled. To check the status of conancenter and to enable, if it is disabled, execute the following commands

       conan remote list
       conan remote enable conancenter

4. There are two Conan profiles `conanprofile_linux` and `conanprofile_windows` available in the `utils/ci/conan/recipe` folder, which will be automatically used in the next step.

   Adjustments

   Check and adjust the compiler version and the path to the MSYS installation in these profiles before running the prepare scripts.

   Note

   The recommended compiler is GCC. Usage of other compilers may lead to unexpected outcomes.

5. To build and install the dependencies, run the script `15_prepare_thirdParty.sh` located in `utils/ci/scripts`.

   1. One of the dependencies of openPASS is OpenScenarioEngine which requires OpenSCENARIO API and it in turn requires JAVA executable to build. If Java executable is not available on your machine, download the java from here and extract the zip file

   2. If `C:\Downloads\zulu` is the extracted path, then add the variable JAVA_HOME to the environmental variable, and append the java executable path to the PATH environmental variable as below

          export JAVA_HOME=/c/Downloads/zulu/
          export PATH=$PATH:/c/Downloads/zulu/bin

   3. The script `15_prepare_thirdParty.sh` also requires the variable PYTHON_EXECUTABLE set. This variable refers to the path of the python installation (For example: It could be either on native Windows or on MSYS). If the python is installed on MSYS then set the variable with the following command.

          export PYTHON_EXECUTABLE=python3

   4. Execute the script `15_prepare_thirdParty.sh` on MSYS

          cd utils/ci/scripts
          ./15_prepare_thirdParty.sh

   1. The script `15_prepare_thirdParty.sh` also requires the variable PYTHON_EXECUTABLE set. This variable refers to the path of the python installation.

          export PYTHON_EXECUTABLE=python3

   2. Execute the script

          cd utils/ci/scripts
          ./15_prepare_thirdParty.sh

6. Upon successful execution of the script, the dependencies will be installed under `C:\deps` on Windows and `~/deps` on Linux.