--- /dev/null
+% FMILIB_Readme.txt\r
+% Readme file for the FMI Library (part of JModelica.org)\r
+% \r
+% Content of this file is used verbatim in doxygen generated documentation.\r
+% The documentation is available online in HTML and PDF form at\r
+% http://www.fmi-library.org\r
+%\r
+\r
+\mainpage FMI Library: part of JModelica.org\r
+\r
+\version 2.0.3\r
+\date 6 November 2017 \r
+\section Summary\r
+FMI library is intended as a foundation for applications interfacing FMUs \r
+(Functional Mockup Units) that follow FMI Standard. This version of the library supports FMI 1.0 and FMI2.0.\r
+See <http://www.fmi-standard.org/> \r
+\r
+The test codes provided with the library can serve as starting point for the \r
+development of custom applications. See Section \ref testing for details.\r
+\r
+\section config Configuring and building\r
+CMake (see <http://www.cmake.org/>) is used to generate the native build scripts\r
+for the library. It is recommended to use "cmake-gui" on Windows or \r
+"ccmake <FMIL source dir>" to configure the build. All the required third party\r
+libraries are included into the distribution.\r
+\r
+CMake 2.8.6 is required since this is the version used in development both on \r
+Windows and Linux. The build script is KNOWN NOT TO WORK WITH CMake 2.8.3 and \r
+below (due to ExternalProject interface changes). CMake 2.8.4 and 2.8.5 are not \r
+tested.\r
+\r
+To build from a terminal command line on Linux or Mac with default settings use:\r
+\code\r
+ mkdir build-fmil; cd build-fmil\r
+ cmake -DFMILIB_INSTALL_PREFIX=<prefix> <path to FMIL source>\r
+ make install test\r
+\endcode\r
+To build in MSYS terminal with g++/gcc on Windows:\r
+\code\r
+ mkdir build-fmil; cd build-fmil\r
+ cmake -DFMILIB_INSTALL_PREFIX=<prefix> -G "MSYS Makefiles" <path to FMIL source>\r
+ make install test\r
+\endcode\r
+To build from command line with Microsoft Visual Studio compilers on Windows:\r
+\code\r
+ mkdir build-fmil; cd build-fmil\r
+ cmake -DFMILIB_INSTALL_PREFIX=<prefix> -G "Visual Studio 10" <path to FMIL source>\r
+ cmake --build . --config MinSizeRel --target install\r
+\endcode\r
+\r
+The primary targets of the library build script are:\r
+- <prefix>/include/fmilib.h \n\r
+ The include file to be used in client applications.\r
+- Library files under <prefix>/lib/ \n\r
+ Static library is named 'fmilib' and shared library 'fmilib_shared'. The \r
+ prefix/suffix of the library files differ depending on the platform. Note \r
+ that if you have configure and built both static and shared library on \r
+ Windows but want to link with the static library compile time define \r
+ "FMILIB_BUILDING_LIBRARY" must be set.\r
+- Doxygen generated documentation under <prefix>/doc/. Note that \r
+ documentation is not generated as part of install target and you need to \r
+ build the 'doc' target separately, i.e., run 'make doc' or explicitly build \r
+ the project in Visual Studio. \r
+ \r
+The following build configuration options are provided:\r
+- \b FMILIB_INSTALL_PREFIX - prefix prepended to install directories.\n\r
+ Default: "../install" \n\r
+ This is the main install directory name. Include files will be located in \r
+ the "include" subdirectory and library files in the "lib" subdirectory. \r
+ Client applications should only include "fmilib.h"\r
+\r
+- \b FMILIB_THIRDPARTYLIBS - thirdparty libaries are currently shipped with \r
+ the library. \r
+\r
+- \b FMILIB_FMI_STANDARD_HEADERS - Path to the FMI standard headers \r
+ directory. Header for specific standards files are expected in \r
+ subdirectories FMI1, FMI2, etc.\n\r
+ Default: "ThirdParty/FMI/default"\r
+\r
+- \b FMILIB_DEFAULT_BUILD_TYPE_RELEASE - Controls build-type used for \r
+ Makefile generation.\n \r
+ Default: ON\n\r
+ If this option is on then 'Release' mode compile flags are used. Otherwize, \r
+ 'Debug' mode flags are generated into the Makefile. The option may be \r
+ overwritten by explicitly setting CMAKE_BUILD_TYPE.\r
+\r
+- \b FMILIB_BUILD_WITH_STATIC_RTLIB Use static run-time libraries (/MT or \r
+ /MTd code generation flags).\n\r
+ Default: OFF\n\r
+ This is only used when generating Microsoft Visual Studio solutions. If the \r
+ options is on then the library will be built against static runtime, \r
+ otherwise - dynamic runtime (/MD or /MDd). Make sure the client code is \r
+ using matching runtime.\r
+\r
+- \b FMILIB_BUILD_STATIC_LIB Build the library as static.\n\r
+ Default: ON\n\r
+ 'fmilib' may be used for static linking.\r
+ \r
+- \b FMILIB_BUILD_SHARED_LIB Build the library as shared (dll/so/dylib).\n\r
+ Default: ON\n\r
+ '\e fmilib_shared' may be used for dynamic linking.\r
+\r
+- \b FMILIB_FMI_PLATFORM - FMI platform defines the subdirectory within FMU \r
+ where binary is located.\n\r
+ The build system will automatically detect win32, win64, linux32, linux64, \r
+ darwin32, darwin64.\r
+\r
+- \b FMILIB_BUILD_FOR_SHARED_LIBS The static library 'fmilib' can be linked \r
+ into shared libraries.\n\r
+ Default: ON\n\r
+ On LINUX position independent code (-fPIC) must be used on all files to be \r
+ linked into a shared library (.so file). On other systems this is not \r
+ needed (either is default or relocation is done).\r
+ Set this option to OFF if you are building an application on Linux and use \r
+ static library only.\r
+\r
+- \b FMILIB_ENABLE_LOG_LEVEL_DEBUG Enable log level \e 'debug'. \n\r
+ Default: OFF\n\r
+ If the option is OFF then the debug level messages are not compiled in.\r
+\r
+- \b FMILIB_GENERATE_DOXYGEN_DOC Enable doxygen target.\n\r
+ Default: ON\n\r
+ You need Doxygen to be installed on the system for this option to have an\r
+ effect.\r
+\r
+- \b FMILIB_BUILD_TESTS Enable build of the tests supplied with the library.\n\r
+ Default: ON\n\r
+ \c RUN_TESTS - target will be provided in Visual Studio. 'make test' will \r
+ run tests on Makefile based platforms.\r
+ \r
+- \b FMILIB_BUILD_BEFORE_TESTS Force build before testing, i.e., building the \r
+ FMI library becomes the first test.\n\r
+ Default: ON\r
+\r
+- \b FMILIB_LINK_TEST_TO_SHAREDLIB Link the tests to fmilib_shared (if built) \r
+ instead of static fmilib.\n\r
+ Default: ON\r
+\r
+- \b FMILIB_GENERATE_BUILD_STAMP Generate a build time stamp and include in \r
+ into the library. \n\r
+ Default: OFF\n\r
+ The function \e fmilib_get_build_stamp() may be used to retrieve the time \r
+ stamp. \code const char* fmilib_get_build_stamp(void); \endcode\r
+\r
+- \b FMILIB_BUILD_LEX_AND_PARSER_FILES Generate scanner and parser for variable\r
+ name syntax checking. Requiers Flex and Bison commands to be specified. Please\r
+ read src/XML/NOTE if using this option. Can only be used on windows. Only\r
+ tested with versions 2.4.3/2.5.3.\r
+\r
+- \b BISON_COMMAND Specifies the path to the Bison executable. Only visible if\r
+ FMILIB_BUILD_LEX_AND_PARSER_FILES is checked.\r
+\r
+- \b FLEX_COMMAND Specifies the path to the Flex executable. Only visible if\r
+ FMILIB_BUILD_LEX_AND_PARSER_FILES is checked.\r
+\r
+\section testing Automatic tests\r
+The FMI library comes with a number of automatic tests. Building of the test \r
+is controlled by \a FMILIB_BUILD_TESTS configuration option. The test \r
+porgrams are also intended as examples of library usage.\n\r
+ The tests can be run in Visual Studio by building project \e RUN_TESTS. For \r
+Makefile based configurations (MSYS, Linux, Mac OSx) run 'make test'.\n \r
+Output from the test programs and test logs can be found in the \e Testing \r
+folder in the build directory.\r
+\r
+The supplied tests are:\r
+- \b ctest_build_all \n\r
+Build the library. This test is controlled by \a FMILIB_BUILD_BEFORE_TESTS \r
+configuration option.\r
+- \b ctest_fmi_zip_unzip_test \n\r
+Basic unzip functionality test. Test executable is \e fmi_zip_unzip_test.\r
+- \b ctest_fmi_zip_zip_test \n\r
+Basic zip functionality test. Test executable is \e fmi_zip_zip_test.\r
+- \b ctest_fmi1_check_variable_naming_conventions_test \n\r
+Tests the name checker functionality to follow the variable naming conventions. \r
+Test executable is \e ctest_fmi1_check_variable_naming_conventions_test, main\r
+source file is \ref ctest_fmi1_check_variable_naming_conventions_test.c.\r
+\e fmi_import_me_test, main source file is \ref fmi_import_me_test.c.\r
+- \b ctest_fmi_import_me_test \n\r
+Load a basic model exchange FMU and simulate it. Test executable is \r
+\e fmi_import_me_test, main source file is \ref fmi_import_me_test.c.\r
+- \b ctest_fmi_import_cs_test \n\r
+Load a basic co-simulation FMU and simulate it. Test executable is \r
+\e fmi_import_cs_test, main source file is \ref fmi_import_cs_test.c.\r
+- \b ctest_fmi_import_cs_tc_test \n\r
+Load a basic co-simulation tools coupling FMU and simulate it. Test executable is \r
+\e fmi_import_cs_test, main source file is \ref fmi_import_cs_test.c.\r
+- \b ctest_fmi_import_xml_test, \b ctest_fmi_import_xml_test_empty, \r
+\b ctest_fmi_import_xml_test_mf \n\r
+Load a small model description XML file and print out detailed information on \r
+it. Test executable is \e fmi_import_xml_text, main source file is \r
+\ref fmi_import_xml_test.cc. The test is run on three different XML files.\r
+This test depends on the success of the \e ctest_fmi_import_cs_test. \r
+- \b ctest_fmi1_capi_cs_test \n\r
+Low level test of FMI CAPI functionality for co-simulation. Test executable \r
+is \e fmi1_capi_cs_test.\r
+- \b ctest_fmi1_capi_me_test \n\r
+Low level test of FMI CAPI functionality for model exchange. Test executable \r
+is \e fmi1_capi_me_test.\r
+- \b ctest_fmi1_logger_test_run \n\r
+Run logger test generating output fmi1_logger_test_output.txt. Test \r
+executable is \e fmi1_logger_test.\r
+- \b ctest_fmi1_logger_test_check \n\r
+Check that the logger test output generated by \b ctest_fmi1_logger_test_run \r
+is identical with the reference file found in the \b Test subdirectory.\r
+- \b ctest_fmi2_check_variable_naming_conventions_test \n\r
+Tests the name checker functionality to follow the variable naming conventions. \r
+Test executable is \e ctest_fmi2_check_variable_naming_conventions_test, main\r
+source file is \ref ctest_fmi2_check_variable_naming_conventions_test.c.\r
+- \b ctest_fmi2_import_xml_test_empty, \b ctest_fmi2_import_xml_test_me,\r
+\b ctest_fmi2_import_xml_test_cs, \b ctest_fmi2_import_xml_test_mf \n\r
+Same as \b ctest_fmi_import_xml_test for FMI 2.0 modules. Test executable\r
+is \e fmi2_import_xml_test.exe, main source file \ref fmi2_import_xml_test.cc.\r
+- \b ctest_fmi2_import_test_me \n\r
+Load a basic FMI 2.0 model exchange FMU and simulate it. Test executable is \r
+\e fmi2_import_me_test, main source file is \ref fmi2_import_me_test.c.\r
+- \b ctest_fmi2_import_test_cs \\r
+Load a basic FMI 2.0 co-simulation FMU and simulate it. Test executable is \r
+\e fmi2_import_cs_test, main source file is \ref fmi2_import_me_test.c.\r
+- \b ctest_fmi_import_test_no_xml, \b ctest_fmi_import_test_me_1,\r
+\b ctest_fmi_import_test_cs_1, \b ctest_fmi_import_test_me_2, \r
+\b ctest_fmi_import_test_cs_2 \n\r
+Test library functionality of handling FMUs with different standard interfaces\r
+within a single application. Test executable is \e fmi_import_test.exe. Main\r
+source file is \ref fmi_import_test.c\r
+\r
+\section logging Using logs\r
+In the text below we consider an FMU importing application (referenced as an \r
+'application') that uses the FMIL. The library is designed to send log \r
+messages to a logger callback function ::jm_logger_f provided as a part of \r
+::jm_callbacks structure in the call to fmi_import_allocate_context(). The \r
+logging/error reporting functions within FMIL support following modes: \r
+-# An importing application relies on default logging functions provided by \r
+FMIL and only chooses the log-level \r
+ - FMIL provides default jm logger callback (See jm_callbacks.h \r
+ jm_default_logger())\r
+ - FMIL provides default fmi logger callback for each standard version.\r
+ See fmi1_import_convenience.h fmi1_default_callback_logger() and\r
+ fmi2_import_convenience.h fmi2_default_callback_logger().\r
+-# An application provides a callback for reporting error messages according \r
+ to jm_callbacks.h (::jm_logger_f) \r
+ - Only errors from FMIL can be propagated to this callback in a \r
+ thread-safe manner for FMI1. \r
+ Imported FMUs may still use the default callback provided by the library. \r
+ This is since logger function in FMI 1.0 standard is context \r
+ independent. The non-thread safe implementation on the FMI1 callback can \r
+ be found in fmi1_import_convenience.h fmi1_log_forwarding().\n\r
+ In FMI 2 the fmiComponentEnvironment can be utilized to forward \r
+ messages from the default fmi2 logger function as provided by the library \r
+ to the user defined ::jm_logger_f function. The fmi2_log_forwarding() \r
+ function expects the context to be set to ::fmi2_import_t.\r
+-# An importing application provides logging function according to the specific\r
+ FMI standard version.\r
+ - Errors from FMIL may be forwarded to this callback. There is a function \r
+ that translates calls according to jm_callbacks.h ::jm_logger_f into calls \r
+ according to fmi_functions.h fmi_callbacks_logger_ft (see \r
+ fmi1_import_init_logger() or fmi2_import_init_logger() that are used to setup \r
+ 'forwarding').\n\r
+ Setting of the callback can only be done at the stage where FMU standard \r
+ is known.\r
+-# An importing application may choose not to use logging function but rely on \r
+ return codes and jm_get_last_error() \r
+ - jm_logger function should be set to NULL\r
+ - Errors from a FMI 1.0 fmu1 cannot be handled this way in a thread-safe \r
+ way (see point 2 above). It works fine with FMI 2.0.\r
+ \r
Code Review / simantics / fmil.git / blobdiff