Newer
Older
# MantleAPI
A collection of interfaces for abstraction between a scenario engine and an environment simulator.
It is intended to be usable with a wide variety of scenario description languages by implementing according scenario engines.
Remark: This is currently work in progress and no stable state is reached yet.
## Used libraries
### Units
License: MIT License
URL: https://github.com/nholthaus/units
Version: v2.3.3
### GoogleTest
License: BSD-3-Clause License
URL: https://github.com/google/googletest
Version: v1.12.1
### CPM
License: MIT License
URL: https://github.com/cpm-cmake/CPM.cmake
Version: v0.36.0
## Build
In order to build this project please consider the following sections.
The used configuration for all setups is `Debug`. For release builds change the configuration to `Release`.
### Windows wsl2 Ubuntu and on Linux/Ubuntu native (prefered)
Install Requirements:
```
Michael Behrisch
committed
sudo apt install graphviz doxygen cmake g++
```
1. Build via cmake:
```
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=$PWD/install
cmake --build build -j
cmake --install build
```
2. Build doc:
```
cd <path_to_mantle_api>
cmake --build build --target MantleAPI_doc
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
cat <path_to_mantle_api>/build/doc/html/index.html
```
3. Test via ctest:
```
cd <path_to_mantle_api>/build
ctest --stop-on-failure
```
ctest runs the tests from both build targets: `CommonTests` and `MentleAPITests`.
### Windows mingw with cmake
This section introduces a step by step guide to install the requirements to build this API with mingw tooling.
Requirements:
- Follow the following guide to set up the mingw64 shell and the required dependencies (cmake, gcc, ninja, doxygen, graphviz): https://www.eclipse.org/openpass/content/html/installation_guide/20_install_prerequisites.html#installing-the-binary-packages
Build via cmake (on a mingw console):
1. Go to the project dir: `cd <project_dir>`
2. Build via cmake:
```
mkdir build
cd build
cmake -G "Ninja" ..
ninja
```
3. Test the API
```
cd <path_to_mantle_api>/build/test
./MantleAPITest.exe
```
4. Build Doc:
```
cd <path_to_mantle_api>/build
cmake --build . --target MantleAPI_doc
```
### Windows native with cmake
This section introduces a step by step guide to install the requirements to build this API with native tooling.
Requirements:
- install cmake: https://cmake.org/install/
- install Visual Studio build tools 2022: https://visualstudio.microsoft.com/downloads/#remote-tools-for-visual-studio-2022
- install doxygen: https://www.doxygen.nl/download.html
- install graphviz: https://graphviz.org/download/
Add doxygen, graphiz, and cmake to at least the current users PATH variable.
1. Configure:
```
cmake.exe --no-warn-unused-cli -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_BUILD_TYPE:STRING=Debug "-DCMAKE_C_COMPILER:FILEPATH=C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\Llvm\bin\clang.exe" "-DCMAKE_CXX_COMPILER:FILEPATH=C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\Llvm\bin\clang.exe" -S<path_to_mantle_api> -B<path_to_mantle_api>/build -G Ninja
```
2. Build:
```
cmake.exe --build <path_to_mantle_api>/build --config Debug --target all --
```
3. Run Tests:
Common Test:
```
$> ."<path_to_mantle_api>/build/CommonTest.exe"
Running main() from gmock_main.cc
...
```
Mantle API Test:
```
$> ."<path_to_mantle_api>/build/MantleAPITest.exe"
Running main() from gmock_main.cc
...
```
4. Build Doc:
```
cmake.exe --build <path_to_mantle_api>/build --config Debug --target MantleAPI_doc --
```
The generated html doc is located here: `<path_to_mantle_api>/build/doc/html/index.html`
## Usage in your own project with cmake
1. Adding it to your own CMakeLists.txt similar to:
```
find_package(MantleAPI)
if (MantleAPI_FOUND)
add_executable(testmantle testmantle_main.cpp)
target_link_libraries(testmantle MantleAPI::MantleAPI)
endif()
```
2. Then make sure that your cmake call finds mantle-api like this:
```
cmake -DCMAKE_PREFIX_PATH=<path_to_mantle_api>/install
```
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
## Developer Notes
### Versioning
Versioning should follow the semantic versioning pattern `MAJOR.MINOR.PATCH`.
Currently this is a manual task that needs to be approved as a part of a code review.
In the following a course guideline is given, when to increment the according fields:
**Major:**
- Even minor changes to a public header will most likely result in an increase of this number (= breaking change).
As this is probably the most common case MAJOR will therefore be incremented relatively frequently compared to other libraries.
**Minor:**
- Increments, if changes are ABI compatible, i.e. independent of the rest of other mantle definitions.
It is expected that this does not happen very often at the current state of development.
- Features related to testing, such as enhancing mocks, adding tests, etc.
- Features related to chore tasks, such as CI scripts, CMake enhancements, formatters, etc.
**Patch:**
- Fixing typos in the documentation (as long as they don't change the semantic of a function call!)
- Fixing bugs related to testing
- Fixing bugs related to chore tasks