Changeset 6b651eb6 in OpenModelica


Ignore:
Timestamp:
2021-11-26T09:50:12+01:00 (2 years ago)
Author:
GitHub <noreply@…>
Branches:
maintenance/v1.19, maintenance/v1.20, maintenance/v1.21, maintenance/v1.22, maintenance/v1.23, master, omlib-staging
Children:
da94d68a
Parents:
4fb12f37
git-author:
Francesco Casella <francesco.casella@…> (11/26/21 09:50:12)
git-committer:
GitHub <noreply@…> (11/26/21 09:50:12)
Message:

Update package management section in the User's Guide (#8146)

  • Update package management section

This text reflects the discussions I had with @sjoelund and @adeas31 to the best of my understanding, regarding the behaviour of the package manager and the intended behaviour of the new package management features in OMEdit.

  • Moved the package management section at the beginning
  • Added reference to OMShell-terminal under Linux
  • Improved documentation based on comments from @sjoelund and @adeas31
Location:
doc/UsersGuide/source
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • doc/UsersGuide/source/index.rst

    raae2bf02 r6b651eb6  
    1919
    2020  introduction
     21  packagemanager
    2122  omedit
    2223  plotting
    … …  
    4344  jupyteropenmodelica
    4445  scripting_api
    45   packagemanager
    4646  omchelptext
    4747  simulationflags

  • doc/UsersGuide/source/introduction.rst

    r7e0d8c8 r6b651eb6  
    178178The following is an interactive session using the interactive session
    179179handler in the OpenModelica environment, called OMShell – the
    180 OpenModelica Shell). Most of these examples are also available in the
     180OpenModelica Shell. Most of these examples are also available in the
    181181:ref:`omnotebook` UsersGuideExamples.onb as well as the testmodels in:
    182182
    … …  
    194194~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    195195
    196 The Windows version which at installation is made available in the start
    197 menu as OpenModelica->OpenModelica Shell which responds with an
    198 interaction window:
     196Under Windows, go to the Start Menu and run OpenModelica->OpenModelica Shell
     197which responds with an interaction window.
     198
     199Under Linux, run ``OMShell-terminal`` to start the interactive session at the prompt.
    199200
    200201We enter an assignment of a vector expression, created by the range

  • doc/UsersGuide/source/packagemanager.rst

    rc89e9872 r6b651eb6  
    1 Package manager
    2 ===============
     1Package Management
     2==================
    33
    4 OpenModelica includes a package manager for installing Modelica packages.
    5 This chapter includes some details on how to install packages and how the package index itself works.
     4Overview of Basic Modelica Package Management Concepts
     5------------------------------------------------------
    66
    7 Installing packages
     7The Modelica language promotes the orderly reuse of component models by means of packages  that contain
     8structured libraries of reusable models. The most prominent example is the Modelica Standard Library (MSL),
     9that contains basic models covering many fields of engineering. Other libraries, both open-source and
     10commercial, are available to cover specific applications domains.
     11
     12When you start a simulation project using Modelica, it is common practice to collect all related system models
     13in a project-specific package that you develop. The models in this package are often instantiated (e.g. by drag-and-drop
     14in OMEdit) from released libraries, which are read-only for your project. This establishes a dependency between your
     15project package and a certain version of a read-only package (or library), which is the one you have loaded in OMEdit
     16and that you drag-and-drop components from.
     17
     18This dependency is automatically marked in your package by adding a `uses annotation
     19<https://specification.modelica.org/maint/3.5/annotations.html#version-handling>`_ at the top level. For example, if you
     20drag and drop components from MSL 4.0.0 into models of your package, the ``annotation(uses(Modelica(version="4.0.0")));``
     21will be added automatically to it. This information allows OpenModelica to automatically load all the libraries
     22that are required to compile the models in your own package next time you (or someone else, possibly on a different
     23computer) loads your package, provided they are installed in places on the computer's file system where OpenModelica
     24can find them.
     25
     26The default place where OpenModelica looks for packages is the so-called
     27`MODELICAPATH <https://specification.modelica.org/maint/3.5/packages.html#the-modelica-library-path-modelicapath>`_.
     28You can check where it is by typing ``getModelicaPath()`` in the Interactive Environment. Installed
     29read-only libraries are placed by default in the MODELICAPATH.
     30
     31When a new version of certain package comes out, `conversion annotations
     32<https://specification.modelica.org/maint/3.5/annotations.html#version-handling>`_ in it declare whether your models using
     33a certain older version of it can be used as they are with the new one, which is then 100% backwards-compatible, or whether
     34they need to be upgraded by running a conversion script, provided with the new version of the package. The former case
     35is declared explicitly by a ``conversion(noneFromVersion)`` annotation. For example, a ``conversion(noneFromVersion="3.0.0")``
     36annotation in version ``3.1.0`` of a certain package means that all packages using version ``3.0.0`` can use ``3.1.0``
     37without any change. Of course it is preferrable to use a newer, backwards-compatible version, as it contains bugfixes
     38and possibly new features.
     39
     40Hence, if you install a new version of a library which is 100% backwards-compatible with the previous ones, all your models that
     41used the old one will automatically load and use the new one, without the need of any further action.
     42
     43If the new version is not backwards-compatible, instead, you will need to create a new version of
     44your library that uses it, by running the provided conversion scripts.
     45
     46OpenModelica has a package manager that can be used to install and update libraries on your computer, and is able to run
     47conversion scripts. Keep in mind there are three stages in package usage: *available* packages are indexed on the
     48OSMC servers and can be downloaded from public repositories;
     49*installed* packages are stored in the MODELICAPATH of your computer; *loaded* packages are loaded in memory
     50in an active OMC session, either via the Interactive Environment, or via the OMEdit GUI, where they are shown in the
     51Libraries Browser. When you load a package, OpenModelica tries to load the best possible installed versions of all
     52the dependencies declared in the uses annotation.
     53
     54The Package Manager
    855-------------------
    956
    10 The following commands setup an empty library directory for generating this documentation.
    11 You probably want to use the default ModelicaPath.
     57The Open Source Modelica Consortium (OSMC) maintains a collection of publicly available, open-source Modelica packages
     58on its servers. They are routinely tested with past released versions of OpenModelica, as well as with the current development
     59version on the master branch, see the `overview report <https://libraries.openmodelica.org/branches/overview-combined.html>`_.
     60Based on the testing results and on information gathered from the library developers, these packages are classified
     61in terms of level of support in OpenModelica. Backwards-compatibility information is also collected from the
     62conversion annotations.
    1263
    13 .. omc-mos ::
     64The OpenModelica Package Manager relies on this information to install the best versions of the library dependencies of your
     65own Modelica packages. It can be run both from the OMEdit GUI and from the command-line interactive environment.
    1466
    15   clear()
    16   system("rm -rf /tmp/omc-pkgman")
    17   setEnvironmentVar("HOME","/tmp/omc-pkgman")
    18   setModelicaPath("/tmp/omc-pkgman/.openmodelica/libraries/")
     67Note that the Package Manager may install multiple builds of the same library version on your PC, if they are indexed on the
     68OSMC servers. When this happens, they are distinguished among each other by means of
     69`semver <https://https://semver.org/#semantic-versioning-specification-semver>`_-style pre- or post-release metadata in the
     70top directory name on the file system. Post-release builds are denoted by a plus sign (e.g. ``2.0.0+build.02``)
     71and have higher priority over the corresponding plain release
     72(e.g. ``2.0.0``), while pre-release builds are denoted by a minus sign (e.g. ``2.0.0-dev.30``) and have a lower priority.
    1973
    20 If you do not manually update the package index, the index is downloaded when trying to install a package.
    21 Update the index when you want to get the latest versions of all Modelica packages.
     74When loading a certain version of a library, unless a specific build is explicitly referenced, the one with higher
     75precedence will always be loaded. For example, if the versions ``2.0.0-beta.01``, ``2.0.0``, and ``2.0.0+build.01``
     76are installed, the latter is loaded by libraries with uses annotation requiring version ``2.0.0``. Unless, of course,
     77there are later backwards-compatible versions installed, e.g., ``2.0.1``, in which case the one with the highest release
     78number and priority is installed.
    2279
    23 .. omc-mos ::
     80In any case, semver version semantics is only used to order the releases, while backwards-compatibility
     81is determined exclusively on the basis of ``noneFromVersion`` annotations.
    2482
    25   clear()
    26   updatePackageIndex()
     83Package Management in OMEdit
     84^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     85TBD: Show how to install new packages and manage installed ones
    2786
    28 You can install a specific version of a package by using `exactMatch=true`.
    29 If a dependency does not have an exact match, another version will be installed.
    30 In this case, the dependencies are available.
     87Running Conversion Scripts in OMEdit
     88^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     89TBD: Show how to run conversion scripts in OMEdit
    3190
    32 .. omc-mos ::
     91Automatically Loaded Packages in OMEdit
     92^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     93When you start OMEdit, some packages are automatically loaded into the environment, and shown in the Libraries
     94Browser. You can configure which ones are loaded from the Tools|Options|Libraries menu.
    3395
    34   clear()
    35   installPackage(Buildings, "1.5.0+build.3", exactMatch=true)
     96Please note that automatically loaded libraries may be in conflict with the dependencies of packages that you may
     97then load from the File menu. For example, if you automatically load MSL ``4.0.0``, and then open a library that
     98uses MSL ``3.2.3``, you get a conflict, because the former is not backwards-compatible with the latter. In this
     99case you have three options:
    36100
    37 You can also specify that the most well-supported version of the package and its dependencies is installed.
    38 The dependencies installed in this case are the same as if the index did not contain the exact match in the previous example.
     101- cancel the operation;
     102- unload the conflicting library, i.e., MSL ``4.0.0``, and load the most recent one compatible with the one
     103  declared in the uses annotation of the opened library, i.e., MSL ``3.2.3``;
     104- upgrade the library you just opened to use the already loaded one, i.e. MSL ``4.0.0``, by running the automatic
     105  conversion script; note that this operation is irreversible and must be carefully planned, considering all the
     106  users of the library that is undergoing automatic conversion.
    39107
    40 .. omc-mos ::
     108Manually Loading Packages
     109^^^^^^^^^^^^^^^^^^^^^^^^^
    41110
    42   clear()
    43   installPackage(Buildings, "1.5.0+build.3")
     111If you want to maintain full control over which libraries are opened, you can use the File | Open Model/Library Files(s)
     112menu command in OMEdit to open the libraries one by one from specific locations in your file system. Note,
     113however, that whenever a library is loaded, its dependencies as declared in the uses annotation will automatically
     114be loaded. If you want to avoid that, you need to load the library dependencies in reverse order, so that the
     115intended library dependencies are already loaded when you open the library that needs them.
    44116
    45 Show that the correct version is now loaded.
     117If you are using the Interactive Environment, you can use the ``loadFile()`` command to load libraries from
     118specific locations on the file system, also in reverse dependency order, unless you also set the optional
     119``uses = false`` input argument to disable the automatic loading of dependencies.
    46120
    47 .. omc-mos ::
     121Using the Package Manager from the Interactive Environment
     122^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    48123
    49   loadModel(Buildings)
    50   getVersion(Buildings)
     124The Package Manager can also be used from the Interactive Environment command line shell. Here is a list
     125of examples of relevant commands; please type them followed by ``getErrorString()``,
     126e.g., ``updatePackageIndex();getErrorString()``, in order to get additional information,
     127notifications and error messages.
    51128
    52 You can also make sure you have the latest versions of all installed packages:
    53 
    54 .. omc-mos ::
    55 
    56   clear()
    57   upgradeInstalledPackages(installNewestVersions=true)
    58 
    59 .. omc-mos ::
    60 
    61   setModelicaPath(OpenModelica.Scripting.getInstallationDirectoryPath()+"/lib/omlibrary")
     129- ``updatePackageIndex()``: this command puts the Package Manager in contact with the OSMC servers and updates
     130    the internally stored list of available packages;
     131- ``getAvailablePackageVersions(Buildings, "")``: lists all available versions of the Buildings library on the OSMC server,
     132   starting from the most recent one, in descending order of priority. Note that pre-release versions have lower priority
     133   than all other versions;
     134- ``getAvailablePackageVersions(Buildings, "7.0.0")``: lists all available versions of the Buildings library on
     135   the OSMC server that are backwards-compatible with version ``7.0.0``, in descending order of priority;
     136- ``installPackage(Buildings, "")``:install the most recent version of the Building libraries, *and all its dependencies*;
     137- ``installPackage(Buildings, "7.0.0")``: install the most recent version of the Building libraries which is backwards-compatible
     138    with version ``7.0.0``, *and all its dependencies*;
     139- ``installPackage(Buildings, "7.0.0", exactMatch = true)``: install version ``7.0.0`` even if there are more recent
     140    backwards-compatible versions available, *and all its dependencies*;
     141- ``upgradeInstalledPackages(installNewestVersions = true)``: installs the latest available version of all installed packages.
    62142
    63143How the package index works
    64144---------------------------
    65145
    66 The package index is generated by `OMPackageManager <https://github.com/OpenModelica/OMPackageManager>`_ on a server.
    67 See its documentation to see how to add new packages to the index, change support level, and so on.
     146The package index is generated by `OMPackageManager <https://github.com/OpenModelica/OMPackageManager>`_ on an OSMC server,
     147based on `these settings <https://github.com/OpenModelica/OMPackageManager/blob/master/repos.json>`_.
     148See its documentation to see how to add new packages to the index, change support level, and so on.
    68149
    69150The index is generated by scanning git repositories on github.
    … …  
    77158* Semantic version: according to the semver specification, but build metadata is also considered (sorted the same way as pre-releases)
    78159* Non-semantic versions: alphabetically
    79 
    80 Packages that are candidates to install:
    81 
    82 * Packages with the same version annotation as the desired version (ignoring pre-release and metadata information)
    83 * Packages listed using a noneFromVersion annotation:
    84 
    85   .. code-block :: modelica
    86 
    87     conversion(noneFromVersion = "3.2.1")
    88 * Packages with a conversion script are not considered (because OpenModelica does not yet support them)
Note: See TracChangeset for help on using the changeset viewer.