Julia bindings to the external C functions of the Modelica Standard Library (MSL): the table functions
(CombiTable1D, CombiTable2D, CombiTimeTable), strings, MAT-file I/O, files and streams, random
numbers and the FFT, and the tool side of ModelicaUtilities.h (ModelicaError and the other callbacks).
It is used by OMBackend.jl to simulate models whose
external functions are in the Standard Library, and it works on its own.
import OMRuntimeExternalC as ORC
ORC.ModelicaStrings_length("hello") # 5
table = [1.0 2.0; 3.0 4.0]
id = ORC.ModelicaStandardTables_CombiTable1D_init2("NoName", "NoName", table, 2, 2, [2], 1, 1, 2, 0)
ORC.ModelicaStandardTables_CombiTable1D_getValue(id, 1, 2.0) # 3.0Everything is in one shared library, libModelicaExternalC (.dylib, .so, .dll). It is compiled from
- the C sources of the Modelica Standard Library, tag
v4.1.0, directoryModelica/Resources/C-Sources(ModelicaStandardTables,ModelicaIO,ModelicaMatIO,ModelicaInternal,ModelicaStrings,ModelicaRandom,ModelicaFFT, with the zlib of that directory), and src/C/ModelicaCallbacks.c, which implementsModelicaUtilities.hfor Julia (ModelicaError,ModelicaFormatMessage,ModelicaAllocateStringand the others).
It links nothing but the C library of the platform: no OpenModelica runtime, no BLAS, no SUNDIALS, no
gettext. It exports the Modelica* functions and the shim's modelica_* and safe_* functions.
C code reports an error with ModelicaError or ModelicaFormatError, which do not return. In this
library such an error is a Julia error (ErrorException, with the message of the C code): the process
goes on, and the library works afterwards.
- The package sets an error handler when it loads (
modelica_set_error_handlerof the shim). An error of any function of the library, and of compiled external C code of a model that callsModelicaError, is thrown from theccallthat was running, asModelica runtime error: <message>. - The
safe_*functions of the shim catch the error in C and return a status; the Julia function throws<function> failed: <message>. Nine file functions ofModelicaIOandModelicaInternalgo this way. - Without a handler (the library loaded by another program), the message goes to stderr and the process
ends (
abort).
When the package loads (never when it precompiles), in this order:
- the directory in the environment variable
OMRUNTIMEEXTERNALC_LIBRARY_DIR, deps/usr/lib(deps/usr/binon Windows) of the package: a build of this checkout (below),- the artifact
ModelicaExternalCofArtifacts.toml, which Pkg installs with the package (tarballs of the platformsaarch64-apple-darwin,x86_64-apple-darwin,x86_64-linux-gnu,aarch64-linux-gnu,x86_64-w64-mingw32, built by the CI and attached to alibs-v*release).
OMRuntimeExternalC.libraryPath() is the path of the loaded library (nothing if there is none, with a
warning when the package loads). The library is loaded with RTLD_GLOBAL, so compiled external C code of
a model that calls ModelicaError and the others finds them in the process.
Needs a C compiler (cc; MinGW gcc in MSYS2 on Windows) and the MSL sources:
git clone --filter=blob:none --no-checkout https://github.com/modelica/ModelicaStandardLibrary.git msl
git -C msl checkout v4.1.0 -- Modelica/Resources/C-Sources
deps/build_libraries.sh msl/Modelica/Resources/C-Sources deps/usr/lib # deps/usr/bin on Windows
deps/check_library.sh deps/usr/lib/libModelicaExternalC.* # dependencies and exportsMACOS_ARCH=x86_64|arm64 cross-compiles on macOS. The build takes about 6 s.
.github/workflows/CI.yml builds the library on the five platforms, checks it and tests the package against it,
on every pull request and push. A pushed tag libs-v1.0.0 (or a run by hand with release_tag set) also
creates that release with the tarballs (Linux built in a manylinux_2_28 container: glibc 2.28 or newer) and hands back the Artifacts.toml for them
(deps/bind_artifacts.jl), which is committed. deps/Yggdrasil/build_tarballs.jl is the draft of a
recipe for a ModelicaExternalC_jll, as the alternative to the artifact.
import Pkg; Pkg.test("OMRuntimeExternalC")They need the library (above). They include a new Julia process that loads the package and checks
that the library is the only one added to the process, and one that loads the package before Glib_jll
(on Windows an unrelated gettext DLL of the earlier bundle broke Glib, OpenModelica/OMBackend.jl#101).
Not every function of the library has a Julia interface. See src/api.jl for the ones that have, and for
how to add another.
A Modelica error leaves the C code where it was reported (the C code frees what it holds before it
reports, as ModelicaError does not return). An error reported on a thread that Julia did not start has
no Julia caller: it must not happen there.
This package is under the OSMC Public License (OSMC-PL) 1.8 or the GNU Affero General Public License version 3 (AGPL v3), at the recipient's choice, like OMFrontend and
OMBackend: LICENSE.md holds both. This covers the Julia code (src/, test/), the C shim
src/C/ModelicaCallbacks.c and the build scripts in deps/.
The C files from the Modelica Standard Library are the MSL's, and the MSL's license applies to them.
libModelicaExternalC is built from the C sources of the Modelica Standard Library
(Modelica/Resources/C-Sources, tag v4.1.0: ModelicaStandardTables, ModelicaIO, ModelicaMatIO,
ModelicaInternal, ModelicaStrings, ModelicaRandom, ModelicaFFT, with the zlib and the matio and kiss_fft
code they contain). Those files are not part of this package and not under the OSMC-PL or the AGPL. They are not copied
into this repository: deps/build_libraries.sh and the CI take them from the Standard Library. They are
licensed by the Modelica Association and contributors under the
3-clause BSD license (each file has the text in its
header), and the zlib sources under the zlib license. THIRD_PARTY_LICENSES.md lists
every compiled file with its copyright holders and license, and has the license texts. It ships with the
library (share/licenses/ModelicaExternalC in the artifact), so a redistributed binary carries the notices
that these licenses require.