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
"Warning: Conflicting versions for loading package Modelica: 3.2.3+maint.om is to be installed, but another package requires version 4.0.0 which is not provided by this version.
[/tmp/omc-pkgman/.openmodelica/libraries//Buildings 1.5.0+build.3:0:0-0:0:readonly] Notification: Buildings 1.5.0+build.3 will not be installed since version 1.5.0+build.3 is installed.
[/tmp/omc-pkgman/.openmodelica/libraries/ModelicaServices 4.0.0+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 58d77b59ed75d8c2f60e436b4169e8e1f1bcfee6).
[/tmp/omc-pkgman/.openmodelica/libraries/Complex 4.0.0+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 58d77b59ed75d8c2f60e436b4169e8e1f1bcfee6).
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 3.2.3+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 68c0c852a12996b0e1c1cad893b0b27c514ac79f).
"

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.
"
>>> 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 1.5.0+build.3:0:0-0:0:readonly] Notification: Buildings 1.5.0+build.3 will not be installed since version 1.5.0+build.3 is installed.
Warning: Conflicting versions for loading package Modelica: 3.2.3+maint.om is to be installed, but another package requires version 4.0.0 which is not provided by this version.
[/tmp/omc-pkgman/.openmodelica/libraries/Buildings 7.0.0/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 903a06999fb514ebc1d0f58ef41b3f6dda0279ed).
[/tmp/omc-pkgman/.openmodelica/libraries//Complex 1.1.0:0:0-0:0:readonly] Notification: Complex 1.1.0 will not be installed since version 1.1.0 is installed.
[/tmp/omc-pkgman/.openmodelica/libraries//Complex 4.0.0+maint.om:0:0-0:0:readonly] Notification: Complex 4.0.0+maint.om will not be installed since version 4.0.0+maint.om is installed.
[/tmp/omc-pkgman/.openmodelica/libraries//Complex 4.0.0+maint.om:0:0-0:0:readonly] Notification: Complex  will not be installed since version 4.0.0+maint.om is installed.
[/tmp/omc-pkgman/.openmodelica/libraries//Modelica 3.2.0+maint.om:0:0-0:0:readonly] Notification: Modelica 3.2.0+maint.om will not be installed since version 3.2.0+maint.om is installed.
[/tmp/omc-pkgman/.openmodelica/libraries//Modelica 3.2.3+maint.om:0:0-0:0:readonly] Notification: Modelica 3.2.3+maint.om will not be installed since version 3.2.3+maint.om is installed.
[/tmp/omc-pkgman/.openmodelica/libraries/ModelicaServices 3.2.3+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 68c0c852a12996b0e1c1cad893b0b27c514ac79f).
[/tmp/omc-pkgman/.openmodelica/libraries/Complex 3.2.3+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 68c0c852a12996b0e1c1cad893b0b27c514ac79f).
[/tmp/omc-pkgman/.openmodelica/libraries/Modelica 4.0.0+maint.om/package.mo:0:0-0:0:readonly] Notification: Package installed successfully (SHA 58d77b59ed75d8c2f60e436b4169e8e1f1bcfee6).
[/tmp/omc-pkgman/.openmodelica/libraries//ModelicaServices 1.1.0:0:0-0:0:readonly] Notification: ModelicaServices 1.1.0 will not be installed since version 1.1.0 is installed.
[/tmp/omc-pkgman/.openmodelica/libraries//ModelicaServices 4.0.0+maint.om:0:0-0:0:readonly] Notification: ModelicaServices 4.0.0+maint.om will not be installed since version 4.0.0+maint.om is installed.
[/tmp/omc-pkgman/.openmodelica/libraries//ModelicaServices 4.0.0+maint.om:0:0-0:0:readonly] Notification: ModelicaServices  will not be installed since version 4.0.0+maint.om is installed.
"
>>> 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)