[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.

[henrikt-ma]

Thank you very much for initiating this!

I have comments, but for a big piece of design like this it isn't always easy to know where to start. Would you be interested in having an online meeting to seek agreement on the general direction first, or should I just start conversations here and there?

I won't have the time to contribute much until after the vacations anyway, but I'll be back mid-August.

[AnHeuermann]

Would you be interested in having an online meeting to seek agreement on the general direction first, or should I just start conversations here and there?

An online meeting sounds like a good idea. I'll send you a mail.

[henrikt-ma]

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.

Just a minor detail on the URIs: Since the URIs are supposed to be resolved relative to the directory containing the .bmo file, I believe they should be relative URIs. Here, this would be base-modelica:Example/PackageA/Library, and I guess this affects URIs in many places of this proposal.

[AnHeuermann]

After some discussion with @henrikt-ma I added an alternative formulation for a mandatory resources layout right next to the Base Modelica file. I like that alternative better since it also introduces natural locations for accompanying files like license or documentation files:

AlternativeStructure <-- mandatory name
├── AlternativeStructure.bmo
├── Documentation
│   └── how-to-use.pdf
├── LICENSE.txt
└── Resources <-- mandatory name
    ├── PackageA
    │   └── Library
    │       └── linux64
    │           ├── libExternalLib1.a
    │           └── libExternalLib2.so
    └── PackageB
        └── Library
            └── linux64
                └── libExternalLib1.a

or maybe

AlternativeStructure <-- mandatory name
├── AlternativeStructure.bmo
├── LICENSE.txt
└── Resources <-- mandatory name
    ├── Documentation
    │   └── how-to-use.pdf
    └── Library
        ├── PackageA
        │   └── linux64
        │       ├── libExternalLib1.a
        │       └── libExternalLib2.so
        └── PackageB
            └── linux64
                └── libExternalLib1.a

In directory AlternativeStructure everything is bundled that is needed to simulate or share the Base Modelica package also called AlternativeStructure.

[henrikt-ma]

This addition should be committed separately to the main MCP branch right away, and then it's the job of this PR to tick the box.

Edit: Now added on the main MCP branch.

[henrikt-ma]

After some discussion with @henrikt-ma I added an alternative formulation for a mandatory resources layout right next to the Base Modelica file.

I couldn't find those layouts in any design document, only in the form of example layouts. Could you provide a section in a design document where conversations can be attached to specific parts of the design alternatives?

[henrikt-ma]

I couldn't find those layouts in any design document, only in the form of example layouts. Could you provide a section in a design document where conversations can be attached to specific parts of the design alternatives?

It's also worth noting that the topic discussed here really is at the heart of another roadmap item in https://github.com/modelica/ModelicaSpecification/blob/MCP/0031/RationaleMCP/0031/ReadMe.md:

• Management of resources and Modelica URIs.

I suppose this just means we will be killing two birds with one stone in the end.