2 % Readme file for the FMI Library (part of JModelica.org)
\r
4 % Content of this file is used verbatim in doxygen generated documentation.
\r
5 % The documentation is available online in HTML and PDF form at
\r
6 % http://www.fmi-library.org
\r
9 \mainpage FMI Library: part of JModelica.org
\r
12 \date 6 November 2017
\r
14 FMI library is intended as a foundation for applications interfacing FMUs
\r
15 (Functional Mockup Units) that follow FMI Standard. This version of the library supports FMI 1.0 and FMI2.0.
\r
16 See <http://www.fmi-standard.org/>
\r
18 The test codes provided with the library can serve as starting point for the
\r
19 development of custom applications. See Section \ref testing for details.
\r
21 \section config Configuring and building
\r
22 CMake (see <http://www.cmake.org/>) is used to generate the native build scripts
\r
23 for the library. It is recommended to use "cmake-gui" on Windows or
\r
24 "ccmake <FMIL source dir>" to configure the build. All the required third party
\r
25 libraries are included into the distribution.
\r
27 CMake 2.8.6 is required since this is the version used in development both on
\r
28 Windows and Linux. The build script is KNOWN NOT TO WORK WITH CMake 2.8.3 and
\r
29 below (due to ExternalProject interface changes). CMake 2.8.4 and 2.8.5 are not
\r
32 To build from a terminal command line on Linux or Mac with default settings use:
\r
34 mkdir build-fmil; cd build-fmil
\r
35 cmake -DFMILIB_INSTALL_PREFIX=<prefix> <path to FMIL source>
\r
38 To build in MSYS terminal with g++/gcc on Windows:
\r
40 mkdir build-fmil; cd build-fmil
\r
41 cmake -DFMILIB_INSTALL_PREFIX=<prefix> -G "MSYS Makefiles" <path to FMIL source>
\r
44 To build from command line with Microsoft Visual Studio compilers on Windows:
\r
46 mkdir build-fmil; cd build-fmil
\r
47 cmake -DFMILIB_INSTALL_PREFIX=<prefix> -G "Visual Studio 10" <path to FMIL source>
\r
48 cmake --build . --config MinSizeRel --target install
\r
51 The primary targets of the library build script are:
\r
52 - <prefix>/include/fmilib.h \n
\r
53 The include file to be used in client applications.
\r
54 - Library files under <prefix>/lib/ \n
\r
55 Static library is named 'fmilib' and shared library 'fmilib_shared'. The
\r
56 prefix/suffix of the library files differ depending on the platform. Note
\r
57 that if you have configure and built both static and shared library on
\r
58 Windows but want to link with the static library compile time define
\r
59 "FMILIB_BUILDING_LIBRARY" must be set.
\r
60 - Doxygen generated documentation under <prefix>/doc/. Note that
\r
61 documentation is not generated as part of install target and you need to
\r
62 build the 'doc' target separately, i.e., run 'make doc' or explicitly build
\r
63 the project in Visual Studio.
\r
65 The following build configuration options are provided:
\r
66 - \b FMILIB_INSTALL_PREFIX - prefix prepended to install directories.\n
\r
67 Default: "../install" \n
\r
68 This is the main install directory name. Include files will be located in
\r
69 the "include" subdirectory and library files in the "lib" subdirectory.
\r
70 Client applications should only include "fmilib.h"
\r
72 - \b FMILIB_THIRDPARTYLIBS - thirdparty libaries are currently shipped with
\r
75 - \b FMILIB_FMI_STANDARD_HEADERS - Path to the FMI standard headers
\r
76 directory. Header for specific standards files are expected in
\r
77 subdirectories FMI1, FMI2, etc.\n
\r
78 Default: "ThirdParty/FMI/default"
\r
80 - \b FMILIB_DEFAULT_BUILD_TYPE_RELEASE - Controls build-type used for
\r
81 Makefile generation.\n
\r
83 If this option is on then 'Release' mode compile flags are used. Otherwize,
\r
84 'Debug' mode flags are generated into the Makefile. The option may be
\r
85 overwritten by explicitly setting CMAKE_BUILD_TYPE.
\r
87 - \b FMILIB_BUILD_WITH_STATIC_RTLIB Use static run-time libraries (/MT or
\r
88 /MTd code generation flags).\n
\r
90 This is only used when generating Microsoft Visual Studio solutions. If the
\r
91 options is on then the library will be built against static runtime,
\r
92 otherwise - dynamic runtime (/MD or /MDd). Make sure the client code is
\r
93 using matching runtime.
\r
95 - \b FMILIB_BUILD_STATIC_LIB Build the library as static.\n
\r
97 'fmilib' may be used for static linking.
\r
99 - \b FMILIB_BUILD_SHARED_LIB Build the library as shared (dll/so/dylib).\n
\r
101 '\e fmilib_shared' may be used for dynamic linking.
\r
103 - \b FMILIB_FMI_PLATFORM - FMI platform defines the subdirectory within FMU
\r
104 where binary is located.\n
\r
105 The build system will automatically detect win32, win64, linux32, linux64,
\r
106 darwin32, darwin64.
\r
108 - \b FMILIB_BUILD_FOR_SHARED_LIBS The static library 'fmilib' can be linked
\r
109 into shared libraries.\n
\r
111 On LINUX position independent code (-fPIC) must be used on all files to be
\r
112 linked into a shared library (.so file). On other systems this is not
\r
113 needed (either is default or relocation is done).
\r
114 Set this option to OFF if you are building an application on Linux and use
\r
115 static library only.
\r
117 - \b FMILIB_ENABLE_LOG_LEVEL_DEBUG Enable log level \e 'debug'. \n
\r
119 If the option is OFF then the debug level messages are not compiled in.
\r
121 - \b FMILIB_GENERATE_DOXYGEN_DOC Enable doxygen target.\n
\r
123 You need Doxygen to be installed on the system for this option to have an
\r
126 - \b FMILIB_BUILD_TESTS Enable build of the tests supplied with the library.\n
\r
128 \c RUN_TESTS - target will be provided in Visual Studio. 'make test' will
\r
129 run tests on Makefile based platforms.
\r
131 - \b FMILIB_BUILD_BEFORE_TESTS Force build before testing, i.e., building the
\r
132 FMI library becomes the first test.\n
\r
135 - \b FMILIB_LINK_TEST_TO_SHAREDLIB Link the tests to fmilib_shared (if built)
\r
136 instead of static fmilib.\n
\r
139 - \b FMILIB_GENERATE_BUILD_STAMP Generate a build time stamp and include in
\r
140 into the library. \n
\r
142 The function \e fmilib_get_build_stamp() may be used to retrieve the time
\r
143 stamp. \code const char* fmilib_get_build_stamp(void); \endcode
\r
145 - \b FMILIB_BUILD_LEX_AND_PARSER_FILES Generate scanner and parser for variable
\r
146 name syntax checking. Requiers Flex and Bison commands to be specified. Please
\r
147 read src/XML/NOTE if using this option. Can only be used on windows. Only
\r
148 tested with versions 2.4.3/2.5.3.
\r
150 - \b BISON_COMMAND Specifies the path to the Bison executable. Only visible if
\r
151 FMILIB_BUILD_LEX_AND_PARSER_FILES is checked.
\r
153 - \b FLEX_COMMAND Specifies the path to the Flex executable. Only visible if
\r
154 FMILIB_BUILD_LEX_AND_PARSER_FILES is checked.
\r
156 \section testing Automatic tests
\r
157 The FMI library comes with a number of automatic tests. Building of the test
\r
158 is controlled by \a FMILIB_BUILD_TESTS configuration option. The test
\r
159 porgrams are also intended as examples of library usage.\n
\r
160 The tests can be run in Visual Studio by building project \e RUN_TESTS. For
\r
161 Makefile based configurations (MSYS, Linux, Mac OSx) run 'make test'.\n
\r
162 Output from the test programs and test logs can be found in the \e Testing
\r
163 folder in the build directory.
\r
165 The supplied tests are:
\r
166 - \b ctest_build_all \n
\r
167 Build the library. This test is controlled by \a FMILIB_BUILD_BEFORE_TESTS
\r
168 configuration option.
\r
169 - \b ctest_fmi_zip_unzip_test \n
\r
170 Basic unzip functionality test. Test executable is \e fmi_zip_unzip_test.
\r
171 - \b ctest_fmi_zip_zip_test \n
\r
172 Basic zip functionality test. Test executable is \e fmi_zip_zip_test.
\r
173 - \b ctest_fmi1_check_variable_naming_conventions_test \n
\r
174 Tests the name checker functionality to follow the variable naming conventions.
\r
175 Test executable is \e ctest_fmi1_check_variable_naming_conventions_test, main
\r
176 source file is \ref ctest_fmi1_check_variable_naming_conventions_test.c.
\r
177 \e fmi_import_me_test, main source file is \ref fmi_import_me_test.c.
\r
178 - \b ctest_fmi_import_me_test \n
\r
179 Load a basic model exchange FMU and simulate it. Test executable is
\r
180 \e fmi_import_me_test, main source file is \ref fmi_import_me_test.c.
\r
181 - \b ctest_fmi_import_cs_test \n
\r
182 Load a basic co-simulation FMU and simulate it. Test executable is
\r
183 \e fmi_import_cs_test, main source file is \ref fmi_import_cs_test.c.
\r
184 - \b ctest_fmi_import_cs_tc_test \n
\r
185 Load a basic co-simulation tools coupling FMU and simulate it. Test executable is
\r
186 \e fmi_import_cs_test, main source file is \ref fmi_import_cs_test.c.
\r
187 - \b ctest_fmi_import_xml_test, \b ctest_fmi_import_xml_test_empty,
\r
188 \b ctest_fmi_import_xml_test_mf \n
\r
189 Load a small model description XML file and print out detailed information on
\r
190 it. Test executable is \e fmi_import_xml_text, main source file is
\r
191 \ref fmi_import_xml_test.cc. The test is run on three different XML files.
\r
192 This test depends on the success of the \e ctest_fmi_import_cs_test.
\r
193 - \b ctest_fmi1_capi_cs_test \n
\r
194 Low level test of FMI CAPI functionality for co-simulation. Test executable
\r
195 is \e fmi1_capi_cs_test.
\r
196 - \b ctest_fmi1_capi_me_test \n
\r
197 Low level test of FMI CAPI functionality for model exchange. Test executable
\r
198 is \e fmi1_capi_me_test.
\r
199 - \b ctest_fmi1_logger_test_run \n
\r
200 Run logger test generating output fmi1_logger_test_output.txt. Test
\r
201 executable is \e fmi1_logger_test.
\r
202 - \b ctest_fmi1_logger_test_check \n
\r
203 Check that the logger test output generated by \b ctest_fmi1_logger_test_run
\r
204 is identical with the reference file found in the \b Test subdirectory.
\r
205 - \b ctest_fmi2_check_variable_naming_conventions_test \n
\r
206 Tests the name checker functionality to follow the variable naming conventions.
\r
207 Test executable is \e ctest_fmi2_check_variable_naming_conventions_test, main
\r
208 source file is \ref ctest_fmi2_check_variable_naming_conventions_test.c.
\r
209 - \b ctest_fmi2_import_xml_test_empty, \b ctest_fmi2_import_xml_test_me,
\r
210 \b ctest_fmi2_import_xml_test_cs, \b ctest_fmi2_import_xml_test_mf \n
\r
211 Same as \b ctest_fmi_import_xml_test for FMI 2.0 modules. Test executable
\r
212 is \e fmi2_import_xml_test.exe, main source file \ref fmi2_import_xml_test.cc.
\r
213 - \b ctest_fmi2_import_test_me \n
\r
214 Load a basic FMI 2.0 model exchange FMU and simulate it. Test executable is
\r
215 \e fmi2_import_me_test, main source file is \ref fmi2_import_me_test.c.
\r
216 - \b ctest_fmi2_import_test_cs \
\r
217 Load a basic FMI 2.0 co-simulation FMU and simulate it. Test executable is
\r
218 \e fmi2_import_cs_test, main source file is \ref fmi2_import_me_test.c.
\r
219 - \b ctest_fmi_import_test_no_xml, \b ctest_fmi_import_test_me_1,
\r
220 \b ctest_fmi_import_test_cs_1, \b ctest_fmi_import_test_me_2,
\r
221 \b ctest_fmi_import_test_cs_2 \n
\r
222 Test library functionality of handling FMUs with different standard interfaces
\r
223 within a single application. Test executable is \e fmi_import_test.exe. Main
\r
224 source file is \ref fmi_import_test.c
\r
226 \section logging Using logs
\r
227 In the text below we consider an FMU importing application (referenced as an
\r
228 'application') that uses the FMIL. The library is designed to send log
\r
229 messages to a logger callback function ::jm_logger_f provided as a part of
\r
230 ::jm_callbacks structure in the call to fmi_import_allocate_context(). The
\r
231 logging/error reporting functions within FMIL support following modes:
\r
232 -# An importing application relies on default logging functions provided by
\r
233 FMIL and only chooses the log-level
\r
234 - FMIL provides default jm logger callback (See jm_callbacks.h
\r
235 jm_default_logger())
\r
236 - FMIL provides default fmi logger callback for each standard version.
\r
237 See fmi1_import_convenience.h fmi1_default_callback_logger() and
\r
238 fmi2_import_convenience.h fmi2_default_callback_logger().
\r
239 -# An application provides a callback for reporting error messages according
\r
240 to jm_callbacks.h (::jm_logger_f)
\r
241 - Only errors from FMIL can be propagated to this callback in a
\r
242 thread-safe manner for FMI1.
\r
243 Imported FMUs may still use the default callback provided by the library.
\r
244 This is since logger function in FMI 1.0 standard is context
\r
245 independent. The non-thread safe implementation on the FMI1 callback can
\r
246 be found in fmi1_import_convenience.h fmi1_log_forwarding().\n
\r
247 In FMI 2 the fmiComponentEnvironment can be utilized to forward
\r
248 messages from the default fmi2 logger function as provided by the library
\r
249 to the user defined ::jm_logger_f function. The fmi2_log_forwarding()
\r
250 function expects the context to be set to ::fmi2_import_t.
\r
251 -# An importing application provides logging function according to the specific
\r
252 FMI standard version.
\r
253 - Errors from FMIL may be forwarded to this callback. There is a function
\r
254 that translates calls according to jm_callbacks.h ::jm_logger_f into calls
\r
255 according to fmi_functions.h fmi_callbacks_logger_ft (see
\r
256 fmi1_import_init_logger() or fmi2_import_init_logger() that are used to setup
\r
258 Setting of the callback can only be done at the stage where FMU standard
\r
260 -# An importing application may choose not to use logging function but rely on
\r
261 return codes and jm_get_last_error()
\r
262 - jm_logger function should be set to NULL
\r
263 - Errors from a FMI 1.0 fmu1 cannot be handled this way in a thread-safe
\r
264 way (see point 2 above). It works fine with FMI 2.0.
\r
Code Review / simantics / fmil.git / blob