Package manager

OpenModelica includes a package manager for installing Modelica packages. This chapter includes some details on how to install packages and how the package index itself works.

Installing packages

The following commands setup an empty library directory for generating this documentation. You probably want to use the default ModelicaPath.

>>> clear()
true
>>> system("rm -rf /tmp/omc-pkgman")
0
>>> setEnvironmentVar("HOME","/tmp/omc-pkgman")
true
>>> setModelicaPath("/tmp/omc-pkgman/.openmodelica/libraries/")
true

If you do not manually update the package index, the index is downloaded when trying to install a package. Update the index when you want to get the latest versions of all Modelica packages.

>>> clear()
true
>>> updatePackageIndex()
true
"[/tmp/omc-pkgman/.openmodelica/libraries/index.json:0:0-0:0:readonly] Notification: Downloaded package index from URL https://libraries.openmodelica.org/index/v1/index.json.
"

You can install a specific version of a package by using exactMatch=true. If a dependency does not have an exact match, another version will be installed. In this case, the dependencies are available.

>>> clear()
true
>>> installPackage(Buildings, "1.5.0+build.3", exactMatch=true)
true
"[/tmp/omc-pkgman/.openmodelica/libraries/ModelicaServices 1.1.0/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA da986cae8f24d6cef27917e0b6f12871f03f84e0).
[/tmp/omc-pkgman/.openmodelica/libraries/Complex 1.1.0/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA da986cae8f24d6cef27917e0b6f12871f03f84e0).
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA da986cae8f24d6cef27917e0b6f12871f03f84e0).
[/tmp/omc-pkgman/.openmodelica/libraries/Buildings 1.5.0+build.3/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 5734e67c306f0cfc46e7e1794da265e16bb22dfa).
"

You can also specify that the most well-supported version of the package and its dependencies is installed. The dependencies installed in this case are the same as if the index did not contain the exact match in the previous example.

>>> clear()
true
>>> installPackage(Buildings, "1.5.0+build.3")
true
"[/tmp/omc-pkgman/.openmodelica/libraries/ModelicaServices 3.2.3+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 52b8895e1e616c9d14e63118a82278a50473f688).
[/tmp/omc-pkgman/.openmodelica/libraries/Complex 3.2.3+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 52b8895e1e616c9d14e63118a82278a50473f688).
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.3+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 52b8895e1e616c9d14e63118a82278a50473f688).
"

Show that the correct version is now loaded.

>>> loadModel(Buildings)
true
"[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Fluid/Dissipation.mo:8490:35-8490:107:writable] Warning: The file was not encoded in UTF-8:
  \"  <html> <p> Calculation of a generic pressure loss in dependence of nom...\".
  Defaulting to 7-bit ASCII with unknown characters replaced by '?'.
  To change encoding when loading a file: loadFile(encoding=\"ISO-XXXX-YY\").
  To change it in a package: add a file package.encoding at the top-level.
  Note: The Modelica Language Specification only allows files encoded in UTF-8.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Fluid/Dissipation.mo:8600:35-8600:107:writable] Warning: The file was not encoded in UTF-8:
  \" <html> <p> Calculation of a generic pressure loss in dependence of nomi...\".
  Defaulting to 7-bit ASCII with unknown characters replaced by '?'.
  To change encoding when loading a file: loadFile(encoding=\"ISO-XXXX-YY\").
  To change it in a package: add a file package.encoding at the top-level.
  Note: The Modelica Language Specification only allows files encoded in UTF-8.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Fluid/Dissipation.mo:8738:35-8738:107:writable] Warning: The file was not encoded in UTF-8:
  \" <html> <p> Calculation of a generic pressure loss in dependence of a pr...\".
  Defaulting to 7-bit ASCII with unknown characters replaced by '?'.
  To change encoding when loading a file: loadFile(encoding=\"ISO-XXXX-YY\").
  To change it in a package: add a file package.encoding at the top-level.
  Note: The Modelica Language Specification only allows files encoded in UTF-8.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Fluid/Dissipation.mo:8793:35-8793:107:writable] Warning: The file was not encoded in UTF-8:
  \" <html> <p> Calculation of a generic pressure loss with linear or quadra...\".
  Defaulting to 7-bit ASCII with unknown characters replaced by '?'.
  To change encoding when loading a file: loadFile(encoding=\"ISO-XXXX-YY\").
  To change it in a package: add a file package.encoding at the top-level.
  Note: The Modelica Language Specification only allows files encoded in UTF-8.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Math/Nonlinear.mo:570:14-570:31:writable] Warning: Treating .0158271919734802 as 0.0158271919734802. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Math/Nonlinear.mo:570:48-570:65:writable] Warning: Treating .0942738402188500 as 0.0942738402188500. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Math/Nonlinear.mo:571:13-571:29:writable] Warning: Treating .155071987336585 as 0.155071987336585. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Math/Nonlinear.mo:571:47-571:63:writable] Warning: Treating .188821573960182 as 0.188821573960182. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Math/Nonlinear.mo:572:9-572:25:writable] Warning: Treating .199773405226859 as 0.199773405226859. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Math/Nonlinear.mo:572:42-572:58:writable] Warning: Treating .224926465333340 as 0.224926465333340. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future.
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.0+maint.om/Math/Nonlinear.mo:572:75-572:91:writable] Warning: Treating .242611071901408 as 0.242611071901408. This is not standard Modelica and only done for compatibility with old code. Support for this feature may be removed in the future.
"
>>> getVersion(Buildings)
"1.5"

You can also make sure you have the latest versions of all installed packages:

>>> clear()
true
>>> upgradeInstalledPackages(installNewestVersions=true)
true
"[/tmp/omc-pkgman/.openmodelica/libraries/Buildings 7.0.0/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 903a06999fb514ebc1d0f58ef41b3f6dda0279ed).
"
>>> setModelicaPath(OpenModelica.Scripting.getInstallationDirectoryPath()+"/lib/omlibrary")
true

How the package index works

The package index is generated by OMPackageManager on a server. See its documentation to see how to add new packages to the index, change support level, and so on.

The index is generated by scanning git repositories on github. All tags and optionally some specific branches are scanned. The tag name is parsed as if it was a semantic version, with prerelease and metadata of the tag added to the version of Modelica packages in the repository. If the tag name is not a semantic version, it is sorted differently.

Packages are sorted as follows:

  • Support level: each package is given a level of support in the index

  • Semantic version: according to the semver specification, but build metadata is also considered (sorted the same way as pre-releases)

  • Non-semantic versions: alphabetically

Packages that are candidates to install:

  • Packages with the same version annotation as the desired version (ignoring pre-release and metadata information)

  • Packages listed using a noneFromVersion annotation:

    conversion(noneFromVersion = "3.2.1")
    
  • Packages with a conversion script are not considered (because OpenModelica does not yet support them)