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
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.
Download MSYS2
The latest 64-bit package is located in the Installation section of MSYS2 website.
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
.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 asMinGW 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.
Open
MSYS2 MinGW 64-bit
and execute the following package managerpacman
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
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”.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.
Update the package database on the system
apt update
Upgrade existing software to latest version
apt upgrade
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 libgmock-dev apt -y install libgtest-dev apt -y install libprotobuf-dev apt -y install libqt5xmlpatterns5-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 qtbase5-dev 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.
Clone openPASS repository
As described above, the checkout path of the repository is assumed to be the default
openpass
.Start
MinGW 64-bit
shellcd /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
shellcd ~ git clone https://gitlab.eclipse.org/eclipse/openpass/opSimulation.git openpass
Navigate into repository and checkout main branch
cd openpass git checkout main
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
There are two Conan profiles
conanprofile_linux
andconanprofile_windows
available in theutils/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.
To build and install the dependencies, run the script
15_prepare_thirdParty.sh
located inutils/ci/scripts
.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
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 belowexport JAVA_HOME=/c/Downloads/zulu/ export PATH=$PATH:/c/Downloads/zulu/bin
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
Execute the script
15_prepare_thirdParty.sh
on MSYScd utils/ci/scripts ./15_prepare_thirdParty.sh
Execute the script
cd utils/ci/scripts ./15_prepare_thirdParty.sh
Upon successful execution of the script, the dependencies will be installed under
C:\deps
on Windows and~/deps
on Linux.