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.

.. omc-mos ::

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

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.

.. omc-mos ::

  clear()
  updatePackageIndex()

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.

.. omc-mos ::

  clear()
  installPackage(Buildings, "1.5.0+build.3", exactMatch=true)

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.

.. omc-mos ::

  clear()
  installPackage(Buildings, "1.5.0+build.3")

Show that the correct version is now loaded.

.. omc-mos ::

  loadModel(Buildings)
  getVersion(Buildings)

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

.. omc-mos ::

  clear()
  upgradeInstalledPackages(installNewestVersions=true)

.. omc-mos ::

  setModelicaPath(OpenModelica.Scripting.getInstallationDirectoryPath()+"/lib/omlibrary")

How the package index works
---------------------------

The package index is generated by `OMPackageManager <https://github.com/OpenModelica/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:

  .. code-block :: modelica

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