[MCP 0031] Base Modelica External Function Interface

[AnHeuermann]

Proposal for #3919.

Summary

Proposes a concrete design for the Base Modelica External Function Interface, covering external C functions and external objects.
The design is loosely modeled after the FMU distribution layout from FMI 3.0: external libraries are bundled alongside the .bmo file in a well-defined directory structure, removing any dependency on MODELICAPATH lookups at import time.

Key design decisions

FORTRAN 77 dropped.
Keep it minimal. Only "C" is permitted as the language specification.
C wrappers can be used where FORTRAN interoperability is required.

Source annotations dropped.
Include, IncludeDirectory, and SourceDirectory are not allowed in Base Modelica.
Only pre-compiled binaries are distributed; compilation of source code is the responsibility of the lowering tool or the modeller.

Restricted annotation set.
The external clause permits only Library, LibraryDirectory, and License.
Both Library and LibraryDirectory are always required explicitly — no defaults are provided.

New base-modelica:/ URI scheme.
Replaces modelica://.
Always relative to the directory of the .bmo file.
The platform (e.g. linux64, win64) is a mandatory subdirectory of LibraryDirectory; placing libraries directly in LibraryDirectory is not allowed.

Naming conflict avoidance.
Including the model name in the LibraryDirectory path (e.g. base-modelica:/Example/PackageA/Library) is recommended to prevent conflicts when two packages provide a library with the same filename.
When two packages within the same model produce a library with the same filename, each must use a separate subdirectory.

External objects.
The class keyword is re-added to Base Modelica to support classes that extend ExternalObject.
The constructor and destructor functions follow the same rules as in full Modelica 12.9.8; no further grammar or semantic changes are required.

Files changed

• external-function-interface.md — new proposal document covering type mapping, the restricted annotation set, the base-modelica:/ URI scheme, library layout, worked examples for external functions and external objects, and a discussion of two design options for representing external objects in Base Modelica.

• grammar.md — three targeted changes:

  • _language-specification_ restricted from _STRING_ to "C" only.
  • _annotation-comment_ in the external clause replaced by a new _external-annotation-comment_ rule that explicitly lists Library, LibraryDirectory, License and strikes out Include, IncludeDirectory, SourceDirectory.
  • class restored in _class-prefixes_ to support external objects.

• differences.md — new External Functions section summarising all of the above decisions.

• examples/ — runnable Modelica packages and generated Base Modelica output demonstrating the full workflow:

  • PackageA / PackageB / Example.mo — two packages that both produce libExternalLib1, showing how separate LibraryDirectory paths resolve the naming conflict.
  • Multiplication / ExternalObjectExample.mo — minimal external object storing a double and exposing a multiply function.
  • Pre-compiled linux64 and win64 libraries for all examples.
  • lower.mos — OpenModelica script to reproduce the .bmo output from the Modelica sources.

Note

To simplify discussion a lot of example code was added. This should be removed for a final version

Tool Prototype

OpenModelica can already lower Modelica to Base Modelica according to this draft with the exception that it doesn't use baseModelica URI or always adds Library and LibraryDirectory explicitly.
It shouldn't be too hard to change it that way. All needed to do is to copy some files / compile some code like OpenModelica already does anyway.