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 packages are located at https://repo.msys2.org/distrib/x86_64/. Download a non-base package, i.e. msys2-x86_64-20200903.exe
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 Source Packages.
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):
# for simulator pacman -S mingw-w64-x86_64-boost # Tested with 1.72.0 pacman -S mingw-w64-x86_64-ccache # Tested with 4.7.4-1 pacman -S mingw-w64-x86_64-cmake # Tested with 3.27.3 pacman -S mingw-w64-x86_64-doxygen # Tested with 1.9.6-2 pacman -S mingw-w64-x86_64-gcc # Tested with 13.2.0 pacman -S mingw-w64-x86_64-gdb # Tested with 13.2.0 pacman -S mingw-w64-x86_64-graphviz # Tested with 2.44.1-12 pacman -S mingw-w64-x86_64-gtest # Tested with 1.14.0 pacman -S mingw-w64-x86_64-make # Tested with 4.4-2 pacman -S mingw-w64-x86_64-qt5-base # Tested with 5.15.3 pacman -S mingw-w64-x86_64-qt5-xmlpatterns # Tested with 5.15.3 # for documentation pacman -S mingw-w64-x86_64-python # Tested with 3.10.9-2 pacman -S mingw-w64-x86_64-python-pip # Tested with 22.3.1-1 pacman -S mingw-w64-x86_64-python-lxml # Tested with 4.9.2-1 # fonts and equation rendering in the documentation pacman -S mingw-w64-x86_64-texlive-bin # Tested with 2022.20220501-4 pacman -S mingw-w64-x86_64-texlive-core # Tested with 2022.20220501-2 pacman -S mingw-w64-x86_64-texlive-font-utils # Tested with 2022.20220501-1 pacman -S mingw-w64-x86_64-texlive-latex-extra # Tested with 2022.20220501-1 pacman -S mingw-w64-x86_64-zziplib # Tested with 0.13.72-3 # documentation with only pacman pacman -S libxslt-devel # Tested with 1.1.37-1 pacman -S mingw-w64-x86_64-python-sphinx # Tested with 5.3.0-1 pacman -S mingw-w64-x86_64-python-sphinx-tabs # Tested with 3.4.1-1 pacman -S mingw-w64-x86_64-python-sphinx_rtd_theme # Tested with 1.1.1-1 pacman -S mingw-w64-x86_64-python-setuptools # Tested with 66.1.0-1 pacman -S mingw-w64-x86_64-python-myst-parser # Tested with 0.18.1-1 # for testing (optional) pacman -S mingw-w64-x86_64-python-pytest # Tested with 7.2.1-1 pacman -S mingw-w64-x86_64-python-pandas # Tested with 1.5.3-1 # for developing purposes (optional) pacman -S mingw-w64-x86_64-clang
Versions
MSYS2 provides rolling release versions, so some packages might be too “up-to-date”.Tested packages - at time of writing - have been listed above as comment.If in doubt, download the package in the right version from the MSYS2 package repository.Install withpacman -U <package-filename>
If there is no old enough MSYS2 Package Version available in the package Repository you can download specific versions with python-pipInstall withpip3 install <package-filename>==<version>
Optional Packages
pacman -S git pacman -S diffutils pacman -S patch pacman -S mingw-w64-x86_64-ag pacman -S mingw-w64-x86_64-qt5-debug pacman -S zlib-devel # for api documentation (optional) pip3 install breathe exhale
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 ccache apt -y install cmake apt -y install doxygen apt -y install googletest apt -y install gcc apt -y install g++ apt -y install graphviz apt -y install libboost-dev apt -y install libqt5xmlpatterns5-dev apt -y install qtbase5-dev apt -y install qtchooser apt -y install zlib1g-dev # for documentation sudo apt install python3 python3-pip libenchant-2-2 dvipng pip3 install sphinx sphinx-rtd-theme sphinx-tabs breathe exhale sphinxcontrib-spelling myst-parser # for testing pip3 install pytest pandas
Under Linux, it is deliberate that the googletest package only installs the header files to the system, but not the static and dynamic libraries. The missing libraries can be build and installed to
/usr/lib
viacd /usr/src/googletest cmake . make make install
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 Source Packages¶
This section describes how to compile prerequisites of openPASS using source packages.
Note
If you are unfamiliar to CMake
or working within a MinGW 64-bit
shell, Section CMake Variables and Options and MSYS2 might give you a short introduction on these topics in the scope of building openPASS itself.
Location Of Installed Source Packages¶
The goal of this section is to download necessary source packages and install them into a suitable directory. This directory will later on be copied into the openPASS repository in order to resolve third party dependency. The following directory tree shows the folder structure, which will be created by following the recommendations of this guide.
Note
The openPASS repository isn’t needed yet.
C:\openpass\thirdParty
├── FMILibrary
│ ├── include
│ └── lib
├── osi
│ ├── include
│ └── lib
├── protobuf
│ ├── bin
│ ├── include
│ └── lib
├── protobuf-shared
│ ├── bin
│ ├── include
│ └── lib
└── zlib-1.2.12
└── contrib
└── minizip
In the folder structure above:
C:\openpass\thirdParty
refers to a temporary directory used to built the prerequisites from source, not theopenpass
repositoryFMILibrary
is the install directory of the Functional Mock-up Interface (FMI) when build from sourceosi
is the install directory of the Open Simulation Interface (OSI) when build from source.protobuf
andprotobuf-shared
are the install directories ofGoogle Protocol Buffers
for shared and static builds, respectively.
~/openpass/thirdParty
├── FMILibrary
│ ├── include
│ └── lib
├── osi
│ ├── include
│ └── lib
├── protobuf
│ ├── bin
│ ├── include
│ └── lib
├── protobuf-shared
│ ├── bin
│ ├── include
│ └── lib
└── zlib-1.2.12
└── contrib
└── minizip
In the folder structure above:
~/openpass/thirdParty
refers to a temporary directory used to built the prerequisites from source, not theopenpass
repositoryFMILibrary
is the install directory of the Functional Mock-up Interface (FMI) when build from sourceosi
is the install directory of the Open Simulation Interface (OSI) when build from source.protobuf
andprotobuf-shared
are the install directories ofGoogle Protocol Buffers
for shared and static builds, respectively.
On the basis of this structure, we will explain further steps.
Build and Install Protobuf¶
Google Protocol Buffers provide the foundation of OSI (see also Build and Install OSI). Due to the usage of OSI different situations (openPASS executables, libraries, tests, FMUs, etc.) static and shared libraries of protobuf have to be provided. This section gives instructions, how to compile version 3.20.0. and hook it into the openPASS build. This currently applies to the openPASS build, as static and shared libraries of Protobuf are required.
Download release 3.20.0 from https://github.com/protocolbuffers/protobuf/releases
Extract
for Windows to
C:\openpass\thirdParty\sources\protobuf-cpp-3.20.0
for Linux to
~/openpass/thirdParty/sources/protobuf-cpp-3.20.0
Navigate to the extracted folder
Start
MinGW 64-bit
shellcd /C/openpass/thirdParty/sources/protobuf-cpp-3.20.0
Start
Bash
shellcd ~/openpass/thirdParty/sources/protobuf-cpp-3.20.0
Create build directory
cd cmake mkdir build cd build
Run CMake
cmake -G "MSYS Makefiles" \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=C:/openpass/thirdParty/protobuf \ -Dprotobuf_BUILD_SHARED_LIBS=OFF \ -Dprotobuf_BUILD_TESTS=OFF \ -DCMAKE_CXX_FLAGS=-fPIC \ ..
cmake -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=$HOME/openpass/thirdParty/protobuf \ -Dprotobuf_BUILD_SHARED_LIBS=OFF \ -Dprotobuf_BUILD_TESTS=OFF \ -DCMAKE_CXX_FLAGS=-fPIC \ ..
Note
Tests are disabled due to compiler warnings treated as errors (may vary with compiler version).
Compile
make -j3
Install
make install
Note
After completion, repeat the steps described above with the following changes applied to the CMake call:
Set
protobuf_BUILD_SHARED_LIBS
toON
and remove -DCMAKE_CXX_FLAGS=-fPIC flag.Use
$HOME/openpass/thirdParty/protobuf-shared
asCMAKE_INSTALL_PREFIX
This creates and installs the Protobuf libraries, as the Protobuf dynamic and static libs are required for the openPASS build.
Build and Install OSI¶
As can be looked up in Open Simulation Interface (OSI), the core component World_OSI
uses OSI as backend storage.
OSI itself uses protobuf
to describe data structures in a platform independent way by means of *.proto files.
When building OSI, these files are converted into C++ headers and sources, using the protobuf compiler protoc
.
Finally, the sources are then compiled into a library.
openPASS finally uses the library and the generated headers to interface the library.
Open and create directory structure
Start
MinGW 64-bit
shellcd /C/ mkdir -p openpass/thirdParty/sources
Start
Bash
shellcd ~ mkdir -p openpass/thirdParty/sources
Download release 3.5.0 from https://github.com/OpenSimulationInterface/open-simulation-interface
Extract
for Windows to
C:\openpass\thirdParty\sources\open-simulation-interface-3.5.0
for Linux to
~/openpass/thirdParty/sources/open-simulation-interface-3.5.0
Navigate to the extracted folder
cd /C/openpass/thirdParty/sources/open-simulation-interface-3.5.0
cd ~/openpass/thirdParty/sources/open-simulation-interface-3.5.0
Optional: Enable Arenas
For better performance, openPASS supports protobuf Arenas allocation (https://developers.google.com/protocol-buffers/docs/reference/arenas). To use this feature, OSI and openPASS needs to be compiled with Arenas support. See WITH_PROTOBUF_ARENA how this feature is enabled in openPASS.
To enable Arenas support for OSI, the line
option cc_enable_arenas = true;
needs to be added manually to all OSI proto files before compilation.This can be achieved in two ways. Either the line
option cc_enable_arenas = true;
gets added manually after the second line of each PROTO filefor Windows in
C:\openpass\thirdParty\sources\open-simulation-interface
for Linux in
~/openpass/thirdParty/sources/open-simulation-interface
by using a text editor or one makes use of the stream editor in the shell:
find . -maxdepth 1 -name '*.proto' -exec sed -i '2i option cc_enable_arenas = true;' {} \;
Warning
The first line of each OSI proto file specifies the protobuf syntax used. If Arenas support is added before the syntax specification, errors occur.
Create build directory
mkdir build cd build
Run Cmake and hook Protobuf into OSI
cmake -G "MSYS Makefiles" \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=C:/openpass/thirdParty/osi \ -DCMAKE_PREFIX_PATH=C:/openpass/thirdParty/protobuf-shared/ ..
cmake -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=$HOME/openpass/thirdParty/osi \ -DCMAKE_PREFIX_PATH=$HOME/openpass/thirdParty/protobuf-shared/ ..
Compile
make -j3
Warning
If
protobuf
compiler complains, doprotoc --version
and check if correct protobuf version is used.
Note
If no protobuf is found the path to protoc needs to be first set manually in the terminal.
export PATH=$HOME/openpass/thirdParty/protobuf-shared/bin:$PATH
Install
make install
Documentation
The OSI class documentation is part of the source code and can be compiled using Doxygen. Instructions are located in the OSI
Readme.md
. A pre-compiled version is located here.So far, the documentation does not include the extensions from the openpass-trafficAgents branch.
Build and Install FMIL¶
Download release 2.0.3 from https://github.com/modelon-community/fmi-library
Note
If the required version isn’t listed as proper release, it can be downloaded via Github-Tags
Extract
for Windows to
C:\openpass\thirdParty\sources\fmi-library-2.0.3
for Linux to
~/openpass/thirdParty/sources/fmi-library-2.0.3
Navigate to the extracted folder
Start
MinGW 64-bit
shellcd /C/openpass/thirdParty/sources/fmi-library-2.0.3
Start
Bash
shellcd ~/openpass/thirdParty/sources/fmi-library-2.0.3
Create build directory
mkdir build cd build
Run Cmake
cmake -G "MSYS Makefiles" \ -DFMILIB_INSTALL_PREFIX=C:/openpass/thirdParty/FMILibrary \ -DCMAKE_BUILD_TYPE=Release \ -DFMILIB_BUILD_STATIC_LIB=OFF \ -DFMILIB_BUILD_SHARED_LIB=ON \ ..
cmake -DFMILIB_INSTALL_PREFIX=$HOME/openpass/thirdParty/FMILibrary \ -DCMAKE_BUILD_TYPE=Release \ -DFMILIB_BUILD_STATIC_LIB=OFF \ -DFMILIB_BUILD_SHARED_LIB=ON \ ..
Leave build directory
cd ..
Apply Patch
As FMIL and the internally used FMU Compliance Checker has issues with loading and private entry points, the following patch needs to be applied:
git apply --ignore-whitespace "<path/to>/fmi-library-2.0.3-fixes.patch"
Enter build directory
cd build
Compile
make -j3
Install
make install
Append Minizip Through Installing zlib Library¶
Minizip is a contributed dependency that is not available through the package installed zlib library. To add minizip to the project it is not required to build the whole repository.
Open and create directory structure
Start
MinGW 64-bit
shellcd /C/ mkdir -p openpass/thirdParty/
Start
Bash
shellcd ~ mkdir -p openpass/thirdParty/
Download release v1.2.12 from https://github.com/madler/zlib
Extract
for Windows to
C:\openpass\thirdParty\zlib
for Linux to
~/openpass/thirdParty/zlib