OpenSimulationInterface · pmai · Jun 15, 2023 · Feb 16, 2023 · Mar 13, 2023 · May 9, 2023
diff --git a/README.md b/README.md
@@ -20,47 +20,11 @@ For usage examples, please refer to the official documentation:
   - [OSMPCNetworkProxy](https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/tree/master/examples/OSMPCNetworkProxy)
 
 ## Installation
-##### Dependencies
-Install `cmake` 3.10.2:
-```bash
-$ sudo apt-get install cmake
-```
-Install `pip3` and missing python packages:
-```bash
-$ sudo apt-get install python3-pip python3-setuptools
-```
-Install `protobuf`:
-```bash
-$ sudo apt-get install libprotobuf-dev protobuf-compiler
-```
 
-
-##### Build and install for `C++` usage:
-```bash
-$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
-$ cd open-simulation-interface
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
-$ sudo make install
-```
-
-##### Install for `Python` usage:
-Local:
-```bash
-$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
-$ cd open-simulation-interface
-$ sudo pip3 install virtualenv
-$ virtualenv -p python3 venv
-$ source venv/bin/activate
-$ python3 -m pip install .
-```
-
-Global:
-```bash
-$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
-$ cd open-simulation-interface
-$ sudo pip3 install .
-```
-For Windows installation see [here](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/windows.html) for more information.
+For detailed installation instructions, please refer to the official documentation:
+- [Setting up OSI](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/setting_up_osi.html)
+  - [Installing _protobuf_ for static / dynamic linking](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_prerequisites.html)
+  - [Installing OSI for C++ on Linux](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_linux_cpp.html)
+  - [Installing OSI for Python on Linux](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_linux_python.html)
+  - [Installing OSI for C++ on Windows](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_windows_cpp.html)
+  - [Installing OSI for Python on Windows](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_windows_python.html)
diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc
@@ -71,7 +71,11 @@ include::./architecture/trace_file_example.adoc[leveloffset=+3]
 
 include::./architecture/formatting_scripts.adoc[leveloffset=+3]
 
-== Setting up OSI
+
+// Setting up OSI
+include::./setup/setting_up_osi.adoc[leveloffset=+1]
+
+include::./setup/installing_prerequisites.adoc[leveloffset=+2]
 
 include::./setup/installing_linux_cpp.adoc[leveloffset=+2]
 

diff --git a/doc/setup/including_osi_dev_projects.adoc b/doc/setup/including_osi_dev_projects.adoc
@@ -8,14 +8,14 @@ TODO: Content to be added in future release.
 
 // TODO: Add description of this task.
 
-**Prerequisites**
+Prerequisites::
 
 //TODO: Add prerequisites.
 
-**Steps**
+Steps::
 
 // TODO: Add steps.
 
-**Result**
+Result::
 
 // TODO: Add result.
diff --git a/doc/setup/installing_linux_cpp.adoc b/doc/setup/installing_linux_cpp.adoc
@@ -4,13 +4,11 @@ include::{root-path}_config.adoc[]
 endif::[]
 = Installing OSI for C++ on Linux
 
-**Prerequisites**
+Prerequisites::
 
-* You have installed _cmake_.
-* You have installed _protobuf_.
-* You must have super user privileges.
+* You have installed everything described in <<top-installing-osi-prerequisits>>.
 
-**Steps**
+Steps::
 
 . Open a terminal.
 . Clone the Open Simulation repository.

diff --git a/doc/setup/installing_linux_python.adoc b/doc/setup/installing_linux_python.adoc
@@ -4,14 +4,14 @@ include::{root-path}_config.adoc[]
 endif::[]
 = Installing OSI for Python on Linux
 
-**Prerequisites**
+*Prerequisites::
 
+* You have installed everything described in <<top-installing-osi-prerequisits>>.
 * You have installed _pip3_.
 * You have installed _python-setuptools_.
-* You have installed _protobuf_.
 * For a local installation, you have installed _virtualenv_.
 
-**Steps**
+Steps::
 
 . Open a terminal.
 . Clone the Open Simulation repository.
@@ -42,7 +42,7 @@ source venv/bin/activate
 .. Local installation
 +
 ----
-pip3 install .
+python3 -m pip install .
 ----
 +
 .. Global installation

diff --git a/doc/setup/installing_macos.adoc b/doc/setup/installing_macos.adoc
@@ -8,14 +8,14 @@ TODO: Content to be added in future release.
 
 // TODO: Add description of this task.
 
-**Prerequisites**
+Prerequisites::
 
 //TODO: Add prerequisites.
 
-**Steps**
+Steps::
 
 // TODO: Add steps.
 
-**Result**
+Result::
 
 // TODO: Add result.
diff --git a/doc/setup/installing_prerequisites.adoc b/doc/setup/installing_prerequisites.adoc
@@ -0,0 +1,73 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+[#top-installing-osi-prerequisits]
+= Installing protobuf for static / dynamic linking
+
+== Prerequisites
+
+* You have installed _cmake_ (version 3.10.2 or higher)
+* You must have superuser privileges
+
+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 like first trials to get started with OSI, dynamic linking could be an option as well.
+
+== 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**:
+
+----
+vcpkg install --triplet=x64-windows-static-md protobuf
+----
+
+Build::
+
+For the cmake configuration, we can directly specify our vcpkg installation:
+----
+cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static-md -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -A x64
+cmake --build . --config Release
+----
+
+== Linux
+
+Dynamic linking (NOT RECOMMENDED)::
+
+As already mentioned, shared linking is possible on Linux, but NOT RECOMMENDED.
+However, for dynamic linking install _protobuf_ (version 3.0.0 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 3.0.0 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
+----
diff --git a/doc/setup/installing_windows_cpp.adoc b/doc/setup/installing_windows_cpp.adoc
@@ -4,12 +4,11 @@ include::{root-path}_config.adoc[]
 endif::[]
 = Installing OSI for C++ on Windows
 
-**Prerequisites**
+Prerequisites::
 
-* You have installed _cmake_ as an administrator.
-* You have installed _protobuf_ as an administrator.
+* You have installed everything described in <<top-installing-osi-prerequisits>>.
 
-**Steps**
+Steps::
 
 . Open a terminal as administrator.
 . Clone the Open Simulation repository.

diff --git a/doc/setup/installing_windows_python.adoc b/doc/setup/installing_windows_python.adoc
@@ -4,12 +4,13 @@ include::{root-path}_config.adoc[]
 endif::[]
 = Installing OSI for Python on Windows
 
-**Prerequisites**
+Prerequisites::
 
+* You have installed everything described in <<top-installing-osi-prerequisits>>.
 * You have installed _Python_ with administrator rights.
 * Make sure _Python_ is added to `PATH`.
 
-**Steps**
+Steps::
 
 . Open a terminal.
 . Clone the Open Simulation repository.

diff --git a/doc/setup/setting_up_osi.adoc b/doc/setup/setting_up_osi.adoc
@@ -0,0 +1,6 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+[#top-setting-up-osi]
+= Setting up OSI
diff --git a/doc/setup/using_osi_support_tools.adoc b/doc/setup/using_osi_support_tools.adoc
@@ -8,14 +8,14 @@ TODO: Content to be added in future release.
 
 // TODO: Add description of this task.
 
-**Prerequisites**
+Prerequisites::
 
 //TODO: Add prerequisites.
 
-**Steps**
+Steps::
 
 // TODO: Add steps.
 
-**Result**
+Result::
 
 // TODO: Add result.