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

WindowsLinux

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). In the following, it is assumed that MSYS2 is installed under C:\msys64.

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.

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.

Windows (MSYS2)Linux (Debian Bookworm)

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 simulator` \
       mingw-w64-x86_64-boost \
       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-gtest \
       mingw-w64-x86_64-make \
       mingw-w64-x86_64-qt5-base \
       mingw-w64-x86_64-qt5-xmlpatterns \
       `# 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.

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.

Notes for WindowsNotes for Linux

• 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

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.

   WindowsLinux

   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.

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. The compiler version and the path to the MSYS installation in these profiles can be adjusted to suit your specific environment, if necessary.

   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.

   WindowsLinux

   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_WINDOWS_EXE set. This variable refers to the path of the python installation (For ex: 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_WINDOWS_EXE=python3
      

   4. Execute the script 15_prepare_thirdParty.sh on MSYS

      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.