| | 1 | = Writing libraries compliant to the Modelica specification = |
| | 2 | Writing libraries compliant to the Modelica [https://modelica.org/documents specification] is not easy. Converting libraries that were not written with the (current) specification in mind is also hard as most of the steps need to be performed manually. Here are some hints to help you on the way. |
| | 3 | |
| | 4 | === Graphical annotations === |
| | 5 | OMEdit was written after Modelica 3 was introduced. Because of this, it has no support for Modelica 1 or 2-style graphical annotations. If you want OMEdit to be able to browse your library, you will need to use a tool that knows how to convert these annotations; for example the Dymola demo version. |
| | 6 | |
| | 7 | === File encoding === |
| | 8 | Make sure that the library is encoded in UTF-8 or 7-bit ASCII. It is not UTF-8 encoded if OpenModelica says: |
| | 9 | > Error: The file was not encoded in UTF-8 |
| | 10 | To solve this, convert the files to UTF-8, or manually modify the sources. To automatically convert all sources if you know the current encoding: |
| | 11 | {{{ |
| | 12 | find $(SOURCE_DIRS) -regextype posix-egrep -regex '.*\.(cpp|c|h|mo|tpl)$$' -exec bash -c "iconv -f UTF-8 -t UTF-8 '{}' -o /dev/null 2>tmp || (rm -f tmp && cp '{}' tmp && iconv -f ISO-8859-1 -t UTF-8 tmp -o '{}' && echo Converted {} to UTF-8)" ';' |
| | 13 | }}} |
| | 14 | To manually convert to 7-bit ASCII (as used by the MSL), use HTML entities. For example: `"°C"` becomes `"<html>°C</html>"` and `<html>Linköping</html>` becomes `<html>Linköping</html>` |
| | 15 | |
| | 16 | === Modelica is case-sensitive === |
| | 17 | |
| | 18 | > Error: Expected the package to have name HVAC, but got Hvac. |
| | 19 | Means the file was named HVAC but the contained class did not have the same name. Usually solved by renaming the file. |
| | 20 | |
| | 21 | === Within clauses === |
| | 22 | |
| | 23 | > Error: Expected the package to have within ATplus; but got within ; |
| | 24 | In Modelica 2 and beyond, packages are required to have a `within`-clause saying where in the hierarchy it is. `within ;` is the empty clause, so this message tells you to add the missing clauses. |
| | 25 | To automatically add within-clauses to a library, there exists a utility in our [https://openmodelica.org/git/OpenModelicaLibraries.git git] repository: addMissingWithin.sh. |
| | 26 | |
| | 27 | === Common parsing errors === |
| | 28 | |
| | 29 | > Warning: Treating .5 as 0.5. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future. |
| | 30 | Add the missing 0 or your library might not work if the Modelica grammar needs to be updated. To do this in Notepad++ (or other regex replacing tool such as sed): |
| | 31 | {{{ |
| | 32 | ([*=,;\s-])(\.\d) to \10\2 |
| | 33 | }}} |
| | 34 | |
| | 35 | === Missing Integer to enumeration conversions === |
| | 36 | |
| | 37 | Some tools used to allow comparisons like `E.one == 0` (enumeration type == Integer), which was never allowed in the specification. Change all integer literals to enumeration literals instead. |
| | 38 | Note that in some tools, the function call `Integer(E.one)` will generate an error-message. In this case, it is useful to add a `function EnumToInteger` to convert the enumeration to integer. |
| | 39 | |
| | 40 | === Missing inner declarations === |
| | 41 | Some tools add missing inner declarations automatically if you forgot them. OpenModelica does not, so add them to your example models. A related error is `World world1;`, which is sometimes added by accident. The inner `World` objects needs to be called `world` or the MultiBody model will not work properly. |
| | 42 | |
| | 43 | === Old standards === |
| | 44 | Use `omc +std=2.x` or add `uses(Modelica(version="2.2.2"))` to the package. This might make it work without further conversion. You are recommended to convert the library to MSL 3.2.1 and ModelicaSpec 3.2r2 or above since in particular the standard library is now conforming to the specification. |
