Skip to content

setting_up_osi_cpp.adoc

Latest commit

 

History

History
122 lines (90 loc) · 4.83 KB

setting_up_osi_cpp.adoc

File metadata and controls

122 lines (90 loc) · 4.83 KB

../_config.adoc = Open Simulation Interface (OSI) C++ Bindings

This section explains how to integrate OSI into your own C project. The C bindings are available in the separate osi-cpp repository.

You can refer to an example application in the examples of the OSI Sensor Model Packaging repository.

Prerequisites

  • cmake (version 3.10.2 or higher)

  • git

Checkout the repository with submodules

  1. Open a terminal in your project.

  2. Clone the osi-cpp repository, including sub-modules:

    git clone --recurse-submodules https://github.com/OpenSimulationInterface/osi-cpp.git

Using vcpkg for dependencies (Recommended)

Especially for building on Windows, the use of vcpkg to handle dependencies is recommended.

Prerequisites

  • The environment variable VCPKG_ROOT must be set to the root of your vcpkg installation.

  • For Windows static linking, the static-md triplet is recommended (see also Static/Dynamic Linking explained below)

Steps

  1. Configure the build using the vcpkg preset:

    cmake --preset default

  2. Perform the build:

    cmake --build build

Building without vcpkg

To build without vcpkg, you must ensure necessary prerequisites are installed and detectable by CMake. It is then usually enough to include the osi-cpp repository in your main CMakeLists.txt:

set(LINK_WITH_SHARED_OSI OFF) # Check linking explaination below
add_subdirectory(lib/osi-cpp)
target_link_libraries(YourTarget open_simulation_interface_pic)

Static/Dynamic Linking

Static linking is the recommended way to package OSI FMUs for sharing with others to be integrated in a co-simulation: They should have minimal external dependencies in order to ensure maximum portability. For other use cases dynamic linking could be an option and is thus explained below.

Windows

Dynamic Linking (NOT RECOMMENDED)

Since on Windows symbols are not exported per default, it can be kind of annoying to deal with this during protobuf header generation (see for example https://groups.google.com/g/protobuf/c/PDR1bqRazts). That is an important reason to use static linking.

Static Linking

Static linking might require to manually build protobuf. It is important to notice that on Windows you can also specify how to link against the C runtime. Basically, this can be set in CMake, e.g. https://cmake.org/cmake/help/latest/prop_tgt/MSVC_RUNTIME_LIBRARY.html

Therefore, it could make sense to still dynamically link against the C Runtime when statically linking protobuf / OSI. (This is important e.g. when building shared libraries, since a static C runtime will create an isolated heap for your dll, which can lead to segfaults depending on what you expose on your public interfaces.)

The easiest way to achieve static linking on Windows without setting all the stuff manually in Cmake and building protobuf is to actually install static protobuf with dynamic c-runtime with vcpkg:

Install vcpkg as per the vcpkg documentation. Create a new triplet file for the required combination of static library linking with dynamic runtime (usually needed for dynamic linking to still work): Create a file named x64-windows-static-md.cmake in the triplets directory with the following content:

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)

Now the protobuf libraries can be built automatically using:

vcpkg install --triplet=x64-windows-static-md protobuf

Linux

Dynamic linking (NOT RECOMMENDED)

As already mentioned, shared linking is possible on Linux, but NOT RECOMMENDED. However, for dynamic linking install protobuf (version 2.6.1 or higher) with apt:

sudo apt-get install libprotobuf-dev protobuf-compiler

In the CMakeLists of the OSI project, LINK_WITH_SHARED_OSI has to be enabled.

Static linking

A common error here is to just install protobuf with apt and link against it. This means that your OSI is build statically but still linking dynamically against protobuf. Here, again either protobuf has to build statically from source or some solution e.g. vcpkg needs to be utilized. We recommend the following (as in the README of the OSI project):

Install protobuf (version 2.6.1 or higher) from source with CXXFLAGS="-fPIC" to allow static linking of your OSI FMUs (replace <version> with preferred release):

wget https://github.com/protocolbuffers/protobuf/releases/download/<version>/protobuf-all-<version>.tar.gz
tar -xzf protobuf-all-<version>.tar.gz
cd protobuf-<version>/
./configure --disable-shared CXXFLAGS="-fPIC"
make
sudo make install
sudo ldconfig