# Installing openPASS

This section describes how compile and run openPASS. Please make sure that all prerequisites have been properly installed according to section Installing Prerequisites. If you have strictly followed the instructions, the installed source packages should be located on your machine under `C:\openpass\thirdParty` for Windows and `~/openpass/thirdParty` for Linux. If there is a path deviation, the following commands must be adjusted.

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

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

- Recommended dependency directory within the openPASS repository: `C:\openpass\deps\thirdParty`

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

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

- Recommended dependency directory within the openPASS repository: `~/openpass/deps/thirdParty`

- 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. Create directory structure

       mkdir -p deps/thirdParty

4. Navigate into directory where installed prerequisites are located

       cd /C/openpass/thirdParty

       cd ~/openpass/thirdParty

5. Copy prerequisites into repository (c.f. Installing Prerequisites)

       cp -r osi /C/openpass/deps/thirdParty
       cp -r protobuf /C/openpass/deps/thirdParty
       cp -r protobuf-shared /C/openpass/deps/thirdParty
       cp -r FMILibrary /C/openpass/deps/thirdParty
       cp -r zlib/contrib/minizip /C/openpass/deps/thirdParty

       cp -r osi ~/openpass/deps/thirdParty
       cp -r protobuf ~/openpass/deps/thirdParty
       cp -r protobuf-shared ~/openpass/deps/thirdParty
       cp -r FMILibrary ~/openpass/deps/thirdParty
       cp -r zlib/contrib/minizip /C/openpass/deps/thirdParty

   Once prerequisites are in place, all third party dependencies within `openpass` can be resolved by `CMake`. For `CMake` builds, each installed prerequisite, which is located in its own subdirectory under

   - `C:\openpass\deps\thirdParty` for Windows and

   - `~/openpass/deps/thirdParty` for Linux,

   can be referenced by its path. The reference is made via the CMAKE_PREFIX_PATH environmental variable, which holds a list of directories specifying the installed prerequisite. This will be explained in more detail in the following.

6. Navigate back into repository

       cd /C/openpass

       cd ~/openpass

7. Create build directory and navigate into it

       mkdir build
       cd build

8. Prepare build

   openPASS links against shared libraries, which are located in the paths specified by `CMAKE_PREFIX_PATH`. To be able to install openPASS with resolved dependencies, all libraries found under the paths have to be copied right next to the executable during the installation step. This is done by setting `INSTALL_EXTRA_RUNTIME_DEPS=ON`. If you have followed the instructions strictly, no changes are necessary.

       cmake -G "MSYS Makefiles" \
       -D CMAKE_PREFIX_PATH="C:/openpass/deps/thirdParty/FMILibrary;C:/openpass/deps/thirdParty/osi;C:/openpass/deps/thirdParty/protobuf;C:/openpass/deps/thirdParty/protobuf-shared;C:/msys64/mingw64/bin;C:/openpass/deps/thirdParty/minizip" \
       -D CMAKE_INSTALL_PREFIX=C:/openPASS/bin/core \
       -D CMAKE_BUILD_TYPE=Release \
       -D USE_CCACHE=ON \
       -D WITH_DEBUG_POSTFIX=OFF \
       -D OPENPASS_ADJUST_OUTPUT=OFF \
       -D INSTALL_EXTRA_RUNTIME_DEPS=ON \
       ..

   Note

   - By specifying `INSTALL_EXTRA_RUNTIME_DEPS=ON`, runtime dependencies will be copied to the installation directory when running `make install`. This applies to all dependencies located in the paths specified in `CMAKE_PREFIX_PATH`.

   - Make sure that the path `C:/msys64/mingw64/bin` is the last path in the CMAKE_PREFIX_PATH. Otherwise cmake might find and use local versions of required libraries instead of the ones listed in the thirdparties folder.

       cmake -D CMAKE_PREFIX_PATH="$HOME/openpass/deps/thirdParty/FMILibrary;$HOME/openpass/deps/thirdParty/osi;$HOME/openpass/deps/thirdParty/protobuf;$HOME/openpass/deps/thirdParty/protobuf-shared;$HOME/openpass/deps/thirdParty/minizip" \
       -D CMAKE_INSTALL_PREFIX=/usr/local/openPASS/bin/core \
       -D CMAKE_BUILD_TYPE=Release \
       -D USE_CCACHE=ON \
       -D WITH_DEBUG_POSTFIX=OFF \
       -D OPENPASS_ADJUST_OUTPUT=OFF \
       -D INSTALL_EXTRA_RUNTIME_DEPS=ON \
       ..

   Note

   For a build that goes beyond the default settings, see CMake Variables and Options for more available variables and options that can be set.

9. Optional: Build and execute unit tests

   Starting from `openpass/build`:

       make test ARGS="--output-on-failure -j3"

   Note

   ARGS is optional, but recommended. Adjust parallel build flag `-j3` based on your system.

10. Build documentation

    Starting from `openpass/build`:

        make doc

    Note

    Currently the documentation must be built before openPASS can be successfully installed if the CMake variable WITH_DOC=ON (default).

11. Build simulation core

    Starting from `openpass/build`:

        make -j3 install

    Note

    Again, adjust parallel build flag `-j3` based on your system.