Skip to content

Commit ec5227d

Browse files
PhRosenbergerpmai
PhRosenberger
authored and
pmai
committed
Move installation steps from README to documentation
Signed-off-by: Philipp Rosenberger <philipp.rosenberger@persival.de>
1 parent 7699763 commit ec5227d

7 files changed

+88
-50
lines changed

‎README.md‎

Lines changed: 7 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -20,47 +20,11 @@ For usage examples, please refer to the official documentation:
2020
- [OSMPCNetworkProxy](https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/tree/master/examples/OSMPCNetworkProxy)
2121

2222
## Installation
23-
##### Dependencies
24-
Install `cmake` 3.10.2:
25-
```bash
26-
$ sudo apt-get install cmake
27-
```
28-
Install `pip3` and missing python packages:
29-
```bash
30-
$ sudo apt-get install python3-pip python3-setuptools
31-
```
32-
Install `protobuf`:
33-
```bash
34-
$ sudo apt-get install libprotobuf-dev protobuf-compiler
35-
```
3623

37-
38-
##### Build and install for `C++` usage:
39-
```bash
40-
$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
41-
$ cd open-simulation-interface
42-
$ mkdir build
43-
$ cd build
44-
$ cmake ..
45-
$ make
46-
$ sudo make install
47-
```
48-
49-
##### Install for `Python` usage:
50-
Local:
51-
```bash
52-
$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
53-
$ cd open-simulation-interface
54-
$ sudo pip3 install virtualenv
55-
$ virtualenv -p python3 venv
56-
$ source venv/bin/activate
57-
$ python3 -m pip install .
58-
```
59-
60-
Global:
61-
```bash
62-
$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
63-
$ cd open-simulation-interface
64-
$ sudo pip3 install .
65-
```
66-
For Windows installation see [here](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/windows.html) for more information.
24+
For detailed installation instructions, please refer to the official documentation:
25+
- [Setting up OSI](https://opensimulationinterface.github.io/osi-documentation/#_setting_up_osi)
26+
- [Installing _protobuf_ for static / dynamic linking](https://opensimulationinterface.github.io/osi-documentation/#_installing_prerequisites)
27+
- [Installing OSI for C++ on Linux](https://opensimulationinterface.github.io/osi-documentation/#_installing_osi_for_c_on_linux)
28+
- [Installing OSI for Python on Linux](https://opensimulationinterface.github.io/osi-documentation/#_installing_osi_for_python_on_linux)
29+
- [Installing OSI for C++ on Windows](https://opensimulationinterface.github.io/osi-documentation/#_installing_osi_for_c_on_windows)
30+
- [Installing OSI for Python on Windows](https://opensimulationinterface.github.io/osi-documentation/#_installing_osi_for_python_on_windows)

‎doc/open-simulation-interface_user_guide.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,8 @@ include::./architecture/formatting_scripts.adoc[leveloffset=+3]
7373

7474
== Setting up OSI
7575

76+
include::./setup/installing_prerequisites.adoc[leveloffset=+2]
77+
7678
include::./setup/installing_linux_cpp.adoc[leveloffset=+2]
7779

7880
include::./setup/installing_linux_python.adoc[leveloffset=+2]

‎doc/setup/installing_linux_cpp.adoc‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,7 @@ endif::[]
66

77
**Prerequisites**
88

9-
* You have installed _cmake_.
10-
* You have installed _protobuf_.
11-
* You must have super user privileges.
9+
* You have installed everything described in <<Installing _protobuf_ for static / dynamic linking depending on the use case>>.
1210
1311
**Steps**
1412

‎doc/setup/installing_linux_python.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ endif::[]
66

77
**Prerequisites**
88

9+
* You have installed everything described in <<Installing _protobuf_ for static / dynamic linking depending on the use case>>.
910
* You have installed _pip3_.
1011
* You have installed _python-setuptools_.
11-
* You have installed _protobuf_.
1212
* For a local installation, you have installed _virtualenv_.
1313
1414
**Steps**
@@ -42,7 +42,7 @@ source venv/bin/activate
4242
.. Local installation
4343
+
4444
----
45-
pip3 install .
45+
python3 -m pip install .
4646
----
4747
+
4848
.. Global installation

‎doc/setup/installing_prerequisites.adoc‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
ifndef::include-only-once[]
2+
:root-path: ../
3+
include::{root-path}_config.adoc[]
4+
endif::[]
5+
6+
= Installing _protobuf_ for static / dynamic linking
7+
8+
== Prerequisites
9+
10+
* You have installed _cmake_ (version 3.10.2 or higher).
11+
* You must have super user privileges.
12+
13+
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.
14+
Fo other use cases like first trials to get started with OSI, dynamic linking could be an option, as well.
15+
16+
== Windows
17+
18+
**Dynamic Linking (NOT RECOMMENDED)**
19+
20+
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).
21+
So basically thats one more reason to use static linking.
22+
23+
**Static Linking**
24+
25+
Static linking might require to manually build _protobuf_.
26+
Its important to notice that on windows you can also specify how to link against the C runtime.
27+
Basically this can be set in CMake e.g. https://cmake.org/cmake/help/latest/prop_tgt/MSVC_RUNTIME_LIBRARY.html
28+
29+
Therefore, it could make sense to still dynamically link against the C Runtime when statically linking _protobuf_ / OSI.
30+
(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.)
31+
32+
The easiest way to achieve static linking on Windows without setting all the stuff manually in Cmake and building _protobuf_ is to actually use vcpkg:
33+
34+
**Install static _protobuf_ with dynamic c-runtime with vcpkg:**
35+
36+
----
37+
vcpkg install --triplet=x64-windows-static-md protobuf
38+
----
39+
40+
**Build:**
41+
42+
For the cmake configuration we can directly specify our vcpkg installation:
43+
----
44+
cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static-md -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -A x64
45+
cmake --build . --config Release
46+
----
47+
48+
== Linux
49+
50+
**Dynamic linking (NOT RECOMMENDED)**
51+
52+
As already mentioned, shared linking is possible on linux, but NOT RECOMMENDED.
53+
However, for dynamic linking, install _protobuf_ (version 3.0.0 or higher) with apt:
54+
----
55+
sudo apt-get install libprotobuf-dev protobuf-compiler
56+
----
57+
and in the CMakeLists of the OSI project, `LINK_WITH_SHARED_OSI` has to be enabled.
58+
59+
**Static linking**
60+
61+
A common error here is to just install _protobuf_ with apt and link against it.
62+
This means that your OSI is build statically but still linking dynamically against _protobuf_.
63+
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):
64+
65+
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):
66+
----
67+
wget https://github.com/protocolbuffers/protobuf/releases/download/<version>/protobuf-all-<version>.tar.gz
68+
tar -xzf protobuf-all-<version>.tar.gz
69+
cd protobuf-<version>/
70+
./configure --disable-shared CXXFLAGS="-fPIC"
71+
make
72+
sudo make install
73+
sudo ldconfig
74+
----

‎doc/setup/installing_windows_cpp.adoc‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ endif::[]
66

77
**Prerequisites**
88

9-
* You have installed _cmake_ as an administrator.
10-
* You have installed _protobuf_ as an administrator.
9+
* You have installed everything described in <<Installing _protobuf_ for static / dynamic linking depending on the use case>>.
1110
1211
**Steps**
1312

‎doc/setup/installing_windows_python.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ endif::[]
66

77
**Prerequisites**
88

9+
* You have installed everything described in <<Installing _protobuf_ for static / dynamic linking depending on the use case>>.
910
* You have installed _Python_ with administrator rights.
1011
* Make sure _Python_ is added to `PATH`.
1112

0 commit comments

Comments
 (0)