id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc
6379	Handling libraries in 1.17.0	Francesco Casella	Adeel Asghar	"We plan to support both MSL 3.2.3 and 4.0.0 (the latter with some limitations on Clocked components) in 1.17.0, see #6274. 

This requires to completely re-think the way we handle system (and non-system) libraries in OMEdit. Possibly in a way which can then be easily integrated with the package manager, see #6020.

I made some reflections on the topic. It is clear to me that there are five main use cases in OMEdit

    1. Work with an existing model or package that only uses system libraries, managed via MODELICAPATH
    2. Work with an existing model or package that (also) uses libraries outside MODELICAPATH, e.g., development versions of packages, including the MSL
    3. Start a new model or package from scratch, using the Modelica Standard Library only
    4. Start a new model or package from scratch, using some specific system library, that inevitably uses MSL
    5. Start a new model or package from scratch using some custom user library outside MODELICAPATH

First of all, when OMEdit is loaded, I would start with a blank session. No defaults. People will often work with different projects, some using MSL 3.2.3, some using 4.0.0, there is no reason why one should choose a default.

Case 1. is very easily handled: you open your existing model or package, that includes uses annotations, and those are used by OMC to load the corresponding libraries from the MODELICAPATH. By default, that covers the system directories for libraries, there should be an easy way to edit MODELICAPATH from the GUI, if one wants to add other directories.

Regarding uses annotations, I understand OMEdit creates them automatically as soon as some components from a library are dragged and dropped into a package, so this is going to work smoothly without doing anything special.

Case 2. can be covered if one tweaks the MODELICAPATH, putting custom directories ahead of system ones. Another good way to cover it is to allow people to run .mos scripts that will load libraries from well-specified paths. These scripts could be written manually or, in the future, automatically by OMEdit upon request, and executed from the File Menu and/or from a suitable button in the toolbar.

I believe Case 3. and 4. should be handled by presenting the user with a window that includes a list of installed libraries (MSL first, then other system libraries). One can then click on the required libraries and load them. Then one creates his own model or package, starts dragging and dropping stuff, and that creates the uses annotation automatically. Next time, you just open your model or package and you are back to Case 1. In version 1.18.0, this window will be more tightly integrated with the package manager, and we'll also tackle the issue of upgrading libraries to newer versions of their dependencies.

Basically, this window replaces the File | System Libraries menu, which is too limited, as it does not include different versions of the same library, in particular of the MSL, which is instead essential. I would also split it in two parts, one for the MSL and another one for all the other libraries, given the very special status of the MSL, that should not be downloaded, but comes shipped with the tool.

The only potentially critical issue in Case 4. is that if you select libraries that have dependencies on different versions of the same library, e.g., one system library that uses MSL 3.2.3 and one that uses MLS 4.0.0, chaos would ensue, particularly since we don't yet have conversion scripts. We should have some means to make sure that you can only make selections that make sense.

My suggestion to handle the case when at some point there is a uses annotation that wants to load a library that was already loaded with an incompatible version, (e.g. first I load a library that uses MSL 3.2.3, and then another that uses MSL 4.0.0) is to give a clear *error* message (not a warning) and unload everything. The current status (i.e. we continue anyway with a bland warning) is not good, because it leads to situations where nothing works properly. This is in particular true now that we have MSL 3.2.3 and MSL 4.0.0: currently OMEdit says that we may have problems if the two are incompatible, but we know for sure they are incompatible, and basically nothing at all will work. Better to stay safe and unload everything.

I'm a bit unsure about Case 5. I guess we could add custom libraries with specific file system locations to a section of the installed libraries window, and load them from there. The only problem I see in this case is that if I have multiple versions of library A in different locations in the file system, and multiple versions of library B that uses A in different locations in the file system, when I load a specific version of B, the uses annotation in it will automatically load a version of A that may not be the one I am interested into, and once it's loaded, it won't be unloaded if another version of A is loaded next.

This issue can be fixed by loading the custom libraries in forward order, i.e. first the appropriate MSL, then the indicated version of A, then the indicated version of B. But this is difficult to explain and to handle in general. Also, to replicate Case 5 in the future, you would need to save a .mos file with the appropriate locations.

Maybe for the time being we should suggest users falling under Case 5, which can be classified as advanced, to always use scripts to load libraries at the beginning of the session, and to do so in forward order, to avoid the automatic uses annotation to override their choice. An experienced user should understand that. After all, that's what I've been doing in Dymola for almost 20 years, and it always worked well.

Last, but not least, we should refer users to a man page explaining these concepts the first time they install 1.17.0. The concept should be natural and easy to follow, but we have to make it very explicit the first time.

"	defect	closed	blocker	1.17.0	OMEdit	v1.17.0-dev	fixed		Adrian Pop