diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc index 394b81448..5edbf7e61 100644 --- a/doc/open-simulation-interface_user_guide.adoc +++ b/doc/open-simulation-interface_user_guide.adoc @@ -79,21 +79,10 @@ include::./architecture/formatting_script.adoc[leveloffset=+3] // Setting up OSI include::./setup/setting_up_osi.adoc[leveloffset=+1] -include::./setup/installing_prerequisites.adoc[leveloffset=+2] +include::./setup/setting_up_osi_cpp.adoc[leveloffset=+2] -include::./setup/installing_linux_cpp.adoc[leveloffset=+2] +include::./setup/setting_up_osi_python.adoc[leveloffset=+2] -include::./setup/installing_linux_python.adoc[leveloffset=+2] - -include::./setup/installing_windows_cpp.adoc[leveloffset=+2] - -include::./setup/installing_windows_python.adoc[leveloffset=+2] - -//include::./setup/installing_macos.adoc[leveloffset=+2] - -//include::./setup/using_osi_support_tools.adoc[leveloffset=+2] - -//include::./setup/including_osi_dev_projects.adoc[leveloffset=+2] //== Example use cases for OSI diff --git a/doc/setup/including_osi_dev_projects.adoc b/doc/setup/including_osi_dev_projects.adoc deleted file mode 100644 index 748d4562f..000000000 --- a/doc/setup/including_osi_dev_projects.adoc +++ /dev/null @@ -1,21 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Including OSI in development projects - -TODO: Content to be added in future release. - -// TODO: Add description of this task. - -Prerequisites:: - -//TODO: Add prerequisites. - -Steps:: - -// TODO: Add steps. - -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 deleted file mode 100644 index 39ccacf67..000000000 --- a/doc/setup/installing_linux_cpp.adoc +++ /dev/null @@ -1,56 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Installing OSI for C++ on Linux - -Prerequisites:: - -* You have installed everything described in <>. - -Steps:: - -. Open a terminal. -. Clone the Open Simulation repository. -+ ----- -git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git ----- -+ -. Switch to the repository directory. -+ ----- -cd open-simulation-interface ----- -+ -. Create a new directory for the build. -+ ----- -mkdir build ----- -+ -. Switch to the new directory. -+ ----- -cd build ----- -+ -. Run cmake. - To build a 32-bit target under 64-bit Linux, add `-DCMAKE_CXX_FLAGS="-m32"` to the cmake command. - In this case, protobuf must be in 32-bit mode too. -+ ----- -cmake .. ----- -+ -. Run make. -+ ----- -make ----- -+ -. Install Open Simulation Interface. -+ ----- -sudo make install ----- diff --git a/doc/setup/installing_linux_python.adoc b/doc/setup/installing_linux_python.adoc deleted file mode 100644 index de234498f..000000000 --- a/doc/setup/installing_linux_python.adoc +++ /dev/null @@ -1,66 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Installing OSI for Python on Linux - -== Installing from PyPI - -Steps:: - -. Open a terminal. -+ -. Optionally create and activate a new virtual environment. -+ ----- -python3 -m venv venv -source venv/bin/activate ----- -+ -. Install Open Simulation Interface. -+ ----- -pip install open-simulation-interface ----- - -== Installing from source - -*Prerequisites:: - -* You have installed everything described in <>. -* You have installed _pip_. - -Steps:: - -. Open a terminal. -. Clone the Open Simulation repository. -+ ----- -git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git ----- -+ -. Switch to the repository directory. -+ ----- -cd open-simulation-interface ----- -+ -. Optionally create and activate a new virtual environment. -+ ----- -python3 -m venv venv -source venv/bin/activate ----- -+ -. Install Open Simulation Interface. -.. Local installation -+ ----- -pip install . ----- -+ -.. Global installation -+ ----- -sudo pip install . ----- diff --git a/doc/setup/installing_macos.adoc b/doc/setup/installing_macos.adoc deleted file mode 100644 index cb27d563d..000000000 --- a/doc/setup/installing_macos.adoc +++ /dev/null @@ -1,21 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Installing OSI on MacOS - -TODO: Content to be added in future release. - -// TODO: Add description of this task. - -Prerequisites:: - -//TODO: Add prerequisites. - -Steps:: - -// TODO: Add steps. - -Result:: - -// TODO: Add result. \ No newline at end of file diff --git a/doc/setup/installing_windows_cpp.adoc b/doc/setup/installing_windows_cpp.adoc deleted file mode 100644 index 373172947..000000000 --- a/doc/setup/installing_windows_cpp.adoc +++ /dev/null @@ -1,57 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Installing OSI for C++ on Windows - -Prerequisites:: - -* You have installed everything described in <>. - -Steps:: - -. Open a terminal as administrator. -. Clone the Open Simulation repository. -+ ----- -git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git ----- -+ -. Switch to the repository directory. -+ ----- -cd open-simulation-interface ----- -+ -. Create a new directory for the build. -+ ----- -mkdir build ----- -+ -. Switch to the new directory. -+ ----- -cd build ----- -+ -. Run cmake. - To build a 64-bit target, add `Win64` to the generator name. - In this case, protobuf and protoc.exe must be in 64-bit mode too. -+ ----- -cmake .. [-G ] [-DCMAKE_INSTALL_PREFIX=] ----- -+ - If you used vcpkg to install protobuf, then provide the target and toolchain file information, as follows -+ ----- -cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static-md -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -A x64 [-G ] [-DCMAKE_INSTALL_PREFIX=] ----- - -. Build and install OSI. -+ ----- -cmake --build . [--config Release] -cmake --build . --target install ----- diff --git a/doc/setup/installing_windows_python.adoc b/doc/setup/installing_windows_python.adoc deleted file mode 100644 index 37a2bba30..000000000 --- a/doc/setup/installing_windows_python.adoc +++ /dev/null @@ -1,60 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Installing OSI for Python on Windows - -== Installing from PyPI - -Steps:: - -. Open a terminal. -+ -. Optionally create and activate a new virtual environment. -+ ----- -python -m venv venv -venv\Scripts\activate ----- -+ -. Install Open Simulation Interface. -+ ----- -pip install open-simulation-interface ----- - -== Installing from source - -Prerequisites:: - -* You have installed everything described in <>. -* You have installed _Python_ with administrator rights. -* Make sure _Python_ is added to `PATH`. - -Steps:: - -. Open a terminal. -. Clone the Open Simulation repository. -+ ----- -git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git ----- -+ -. Switch to the repository directory. -+ ----- -cd open-simulation-interface ----- -+ -. Optionally create and activate a new virtual environment. -+ ----- -python -m venv venv -venv\Scripts\activate ----- -+ -. Install Open Simulation Interface. -+ ----- -pip install . ----- diff --git a/doc/setup/installing_prerequisites.adoc b/doc/setup/setting_up_osi_cpp.adoc similarity index 63% rename from doc/setup/installing_prerequisites.adoc rename to doc/setup/setting_up_osi_cpp.adoc index 430499bed..9c101d547 100644 --- a/doc/setup/installing_prerequisites.adoc +++ b/doc/setup/setting_up_osi_cpp.adoc @@ -2,18 +2,64 @@ ifndef::include-only-once[] :root-path: ../ include::{root-path}_config.adoc[] endif::[] -[#top-installing-osi-prerequisits] -= Installing protobuf for static / dynamic linking += 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 https://github.com/OpenSimulationInterface/osi-cpp.git[osi-cpp] repository. + +You can refer to an example application in the examples of the +https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/tree/master/examples[OSI Sensor Model Packaging] repository. == Prerequisites +- cmake (version 3.10.2 or higher) +- git + +== Checkout the repository with submodules + +. Open a terminal in your project. +. 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 <> explained below) + +Steps:: +. Configure the build using the vcpkg preset: ++ +---- +cmake --preset default +---- +. 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) + +---- -* You have installed _cmake_ (version 3.10.2 or higher) -* You must have superuser privileges +== Static/Dynamic Linking [[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 like first trials to get started with OSI, dynamic linking could be an option as well. +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 +=== Windows Dynamic Linking (NOT RECOMMENDED):: @@ -46,7 +92,7 @@ Now the protobuf libraries can be built automatically using: vcpkg install --triplet=x64-windows-static-md protobuf ---- -== Linux +=== Linux Dynamic linking (NOT RECOMMENDED):: diff --git a/doc/setup/setting_up_osi_python.adoc b/doc/setup/setting_up_osi_python.adoc new file mode 100644 index 000000000..eaabe9dcf --- /dev/null +++ b/doc/setup/setting_up_osi_python.adoc @@ -0,0 +1,74 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Open Simulation Interface (OSI) Python Bindings + + +This section explains how to integrate OSI into your own C++ project. +The C++ bindings are available in the separate ttps://github.com/OpenSimulationInterface/osi-python.git[osi-python] repository. + +== Installing using pip (Recommended) + +Currently OSI is not yet published to pypi.org and thus must be installed from the `osi-python`` repository directly. + +Steps:: +. Open a terminal. +. Optionally create and activate a new virtual environment. ++ +[cols="1,1", options="header"] +|=== +| Linux | Windows +| `python3 -m venv venv` + +`source venv/bin/activate` + +| `python -m venv venv` + +`venv\Scripts\activate` +|=== +. Install Open Simulation Interface: ++ +---- +pip install git+https://github.com/OpenSimulationInterface/osi-python.git +---- +. Now you can start a python shell or script and import from `osi3` and `osi3trace` e.g. ++ +---- +python3 -c "from osi3.osi_sensorview_pb2 import SensorView" +---- + +. You can of course specify `osi-python` as dependency in your `pyproject.toml` ++ +---- +[project] +# ... +dependencies = [ + "open-simulation-interface@git+https://github.com/OpenSimulationInterface/osi-python.git" +] +---- + +== Installing from source + +Prerequisites:: +* **Python 3.10 or later**. +* **pip**. + +Steps:: +1. Open a terminal. +2. Clone the osi-python repository: ++ +---- +git clone --recurse-submodules https://github.com/OpenSimulationInterface/osi-python.git +---- +3. Switch to the repository directory: ++ +---- +cd osi-python +---- +4. Optionally create and activate a new virtual environment (see table above). +5. Install Open Simulation Interface: ++ +---- +pip install . +---- \ No newline at end of file diff --git a/doc/setup/using_osi_support_tools.adoc b/doc/setup/using_osi_support_tools.adoc deleted file mode 100644 index 4d856e931..000000000 --- a/doc/setup/using_osi_support_tools.adoc +++ /dev/null @@ -1,21 +0,0 @@ -ifndef::include-only-once[] -:root-path: ../ -include::{root-path}_config.adoc[] -endif::[] -= Using OSI supporting tools - -TODO: Content to be added in future release. - -// TODO: Add description of this task. - -Prerequisites:: - -//TODO: Add prerequisites. - -Steps:: - -// TODO: Add steps. - -Result:: - -// TODO: Add result. \ No newline at end of file