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 packages are located at https://repo.msys2.org/distrib/x86_64/. Download a non-base package, i.e. msys2-x86_64-20200903.exe

  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 Apps

    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.

  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):

    # for simulator
pacman -S mingw-w64-x86_64-boost        #Tested with 1.75.0-2
pacman -S mingw-w64-x86_64-ccache       #Tested with 3.7.9-1
pacman -S mingw-w64-x86_64-cmake        #Tested with 3.19.2-1
pacman -S mingw-w64-x86_64-doxygen      #Tested with 1.8.20-1
pacman -S mingw-w64-x86_64-gcc          #Tested with 10.2.0-6
pacman -S mingw-w64-x86_64-gdb          #Tested with 10.1-2
pacman -S mingw-w64-x86_64-graphviz     #Tested with 2.44.1-3
pacman -S mingw-w64-x86_64-gtest        #Tested with 1.11.0-4
#pacman -S mingw-w64-x86_64-protobuf    # currently uses custom build (3.17.3). See 'Installing the Source Packages' below.
pacman -S mingw-w64-x86_64-qt5          #Tested with 5.15.2-5
pacman -S make                          #Tested with 4.3-1

# for documentation
pacman -S mingw-w64-x86_64-python       #Tested with 3.9.6.2
pacman -S mingw-w64-x86_64-python-pip   #Tested with 21.1.3-2
pacman -S mingw-w64-x86_64-python-lxml  #Tested with 4.6.2-2

# get necessary latex style (assuming default paths for MSYS2)
wget -P /mingw64/share/texmf-dist/tex/latex/anyfontsize \
  http://mirrors.ctan.org/macros/latex/contrib/anyfontsize/anyfontsize.sty

# fonts (picks up anyfontsize) and equation rendering in the documentation
pacman -S mingw-w64-x86_64-zziplib      #Tested with 0.13.72-3
pacman -S mingw-w64-x86_64-texlive-bin  #Tested with 2021.20210424-5
pacman -S mingw-w64-x86_64-texlive-core #Tested with 2021.20210519-2
pacman -S mingw-w64-x86_64-texlive-font-utils #Tested with 2021.20210519-1

# for sphinx/exhale
pacman -S libxslt-devel

# additional python packages for documentation
pip3 install sphinx sphinx-rtd-theme sphinx-tabs breathe exhale sphinxcontrib-spelling

    Versions

    MSYS2 provides rolling release versions, so some packages might be too “up-to-date”.
    Tested packages - ate 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 with pacman -U <package-filename>

  3. Optional Packages

    pacman -S git
pacman -S diffutils
pacman -S patch
pacman -S dos2unix
pacman -S mingw-w64-x86_64-ag
pacman -S mingw-w64-x86_64-qt5-debug
pacman -S zlib-devel

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 the EndToEnd Test Framework shall be used, additional requirements have to be considered.

The test framework is based on Python and some additional Python modules. Installation of the required modules can be accomplished using pip. Please refer to the file requirements.txt located in sim/tests/endToEndTests/pyOpenPASS for a list of dependencies.

The requirements file can be directly passed to pip:

pip install -r requirements.txt

(executed from sim/src/tests/endToEndTests/pyOpenPASS)

Warning

win_only pip install will try to fetch precompiled packages by default. If it is unable to locate a binary package for the current environment, packages will be compiled from source. This step fails for the numpy package when being built from the MSYS2 environment. Thus, it is recommended to set up a native Windows Python environment and perform the installation there. To force the usage of a specific Python environment, the variable Python3_EXECUTABLE can be set to the indended Python interpreter executable during cmake configuration (see Installing OpenPASS).

Please refer to EndToEnd Test Framework for more details for using 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.

C:\OpenPASS\thirdParty
├── FMILibrary
│   ├── include
│   └── lib
├── osi
│  ├── include
│  └── lib
├── protobuf
│  ├── bin
│  ├── include
│  └── lib
└── protobuf-shared
   ├── bin
   ├── include
   └── lib

In the folder structure above:

  • C:\OpenPASS\thirdParty refers to a temporary directory used to built the prerequisites from source, not the simopenpass repository

  • FMILibrary is the install directory of the Functional Mock-up Interface (FMI) when build from source

  • osi is the install directory of the Open Simulation Interface (OSI) when build from source.

  • protobuf and protobuf-shared are the install directories of Google 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. Please refer to Custom Protobuf Build for detailed instructions.

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.

  1. Open and create directory structure

    Start MinGW 64-bit shell

    cd /C/
mkdir -p OpenPASS/thirdParty/sources

  2. Download release 3.3.1 from https://github.com/OpenSimulationInterface/open-simulation-interface

  3. Extract

    • for Windows to C:\OpenPASS\thirdParty\sources\open-simulation-interface-3.3.1

    • for Linux to ~/OpenPASS/thirdParty/sources/open-simulation-interface-3.3.1

  4. Navigate to the extracted folder

    cd /C/OpenPASS/thirdParty/sources/open-simulation-interface-3.3.1

  5. 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_EXTENDED_OSI 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 file

    • for 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.

  6. Create build directory

    mkdir build
cd build

  7. Run Cmake

    cmake -G "MSYS Makefiles" \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=C:/OpenPASS/thirdParty/osi \
      ..

  8. Compile

    make -j3

    Warning

    If protobuf compiler complains, do

    protoc --version

    and check if correct protobuf version is used.

  9. 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

  1. Download release 2.0.3 from https://github.com/modelon-community/fmi-library

  2. Extract

    • for Windows to C:\OpenPASS\thirdParty\sources\fmi-library-2.0.3

    • for Linux to ~/OpenPASS/thirdParty/sources/fmi-library-2.0.3

  3. Navigate to the extracted folder

    Start MinGW 64-bit shell

    cd /C/OpenPASS/thirdParty/sources/fmi-library-2.0.3

  4. Create build directory

    mkdir build
cd build

  5. 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  \
      ..

  6. Leave build directory

    cd ..

  7. 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:

    patch -l -p1 "<path/to>/fmi-library-2.0.3-fixes.patch"

  8. Enter build directory

    cd build

  9. Compile

    make -j3

  10. Install

    make install