Skip to content

Commit 8d887f8

Browse files
PhRosenbergerPhRosenberger
committed
Removing installation steps from README and considering them in docu
Signed-off-by: Philipp Rosenberger <philipp.rosenberger@partner.bmw.de>
1 parent f52aeb3 commit 8d887f8

7 files changed

+89
-50
lines changed

‎README.md‎

Lines changed: 8 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -83,48 +83,13 @@ python3 generate_osi_messages.py
8383
This will output an osi file (`sv_330_361_1000_movingobject.osi`) which can be visualized and played back by the [osi-visualizer](https://github.com/OpenSimulationInterface/osi-visualizer).
8484

8585
See Google's documentation for more tutorials on how to use protocol buffers with [Python](https://developers.google.com/protocol-buffers/docs/pythontutorial) or [C++](https://developers.google.com/protocol-buffers/docs/cpptutorial).
86-
## Installation
87-
##### Dependencies
88-
Install `cmake` 3.10.2:
89-
```bash
90-
$ sudo apt-get install cmake
91-
```
92-
Install `pip3` and missing python packages:
93-
```bash
94-
$ sudo apt-get install python3-pip python3-setuptools
95-
```
96-
Install `protobuf`:
97-
```bash
98-
$ sudo apt-get install libprotobuf-dev protobuf-compiler
99-
```
100-
10186

102-
##### Build and install for `C++` usage:
103-
```bash
104-
$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
105-
$ cd open-simulation-interface
106-
$ mkdir build
107-
$ cd build
108-
$ cmake ..
109-
$ make
110-
$ sudo make install
111-
```
112-
113-
##### Install for `Python` usage:
114-
Local:
115-
```bash
116-
$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
117-
$ cd open-simulation-interface
118-
$ sudo pip3 install virtualenv
119-
$ virtualenv -p python3 venv
120-
$ source venv/bin/activate
121-
$ python3 -m pip install .
122-
```
87+
## Installation
12388

124-
Global:
125-
```bash
126-
$ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
127-
$ cd open-simulation-interface
128-
$ sudo pip3 install .
129-
```
130-
For Windows installation see [here](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/windows.html) for more information.
89+
For detailed installation instructions, please refer to the official documentation:
90+
- [Setting up OSI](https://opensimulationinterface.github.io/osi-documentation/#_setting_up_osi)
91+
- [Installing _protobuf_ for static / dynamic linking](https://opensimulationinterface.github.io/osi-documentation/#_installing_prerequisites)
92+
- [Installing OSI for C++ on Linux](https://opensimulationinterface.github.io/osi-documentation/#_installing_osi_for_c_on_linux)
93+
- [Installing OSI for Python on Linux](https://opensimulationinterface.github.io/osi-documentation/#_installing_osi_for_python_on_linux)
94+
- [Installing OSI for C++ on Windows](https://opensimulationinterface.github.io/osi-documentation/#_installing_osi_for_c_on_windows)
95+
- [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
@@ -69,6 +69,8 @@ include::./architecture/formatting_scripts.adoc[leveloffset=+3]
6969

7070
== Setting up OSI
7171

72+
include::./setup/installing_prerequisites.adoc[leveloffset=+2]
73+
7274
include::./setup/installing_linux_cpp.adoc[leveloffset=+2]
7375

7476
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 (here exemplary for Release `v21.12` a.k.a. _protobuf_ 3.21.12):
66+
----
67+
wget https://github.com/protocolbuffers/protobuf/releases/download/<v21.12>/protobuf-all-21.12.tar.gz
68+
tar -xzf protobuf-all-21.12.tar.gz
69+
cd protobuf-21.12/
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)