diff --git a/README.md b/README.md index 26464592e..47b5c4bc2 100644 --- 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 index c331a566f..90b288a6f 100644 --- 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 index 7138417c8..748d4562f 100644 --- 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. \ No newline at end of file diff --git a/doc/setup/installing_linux_cpp.adoc b/doc/setup/installing_linux_cpp.adoc index 97050578d..39ccacf67 100644 --- 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 <>. -**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 index 771de0b20..b1b84a32c 100644 --- 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 <>. * 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 index 83d64609c..cb27d563d 100644 --- 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. \ No newline at end of file diff --git a/doc/setup/installing_prerequisites.adoc b/doc/setup/installing_prerequisites.adoc new file mode 100644 index 000000000..08eb4df5d --- /dev/null +++ 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 with preferred release): +---- +wget https://github.com/protocolbuffers/protobuf/releases/download//protobuf-all-.tar.gz +tar -xzf protobuf-all-.tar.gz +cd protobuf-/ +./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 index d14208544..f4feb4a35 100644 --- 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 <>. -**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 index e48ccd1f8..ecb3d31cf 100644 --- 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 <>. * 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 new file mode 100644 index 000000000..9119641e5 --- /dev/null +++ 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 index 829bf3d04..4d856e931 100644 --- 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. \ No newline at end of file